From 3a273c60835c672d1f6f543ba2ceb03c733670fc Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 14:53:56 +0000 Subject: [PATCH 01/13] Update coder_ai_task minimum version to v2.24.0 Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/resources/ai_task.md | 3 +++ provider/ai_task.go | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index 1922ef5..30d7eba 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -4,12 +4,15 @@ page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to define Coder tasks. + ~> Note: This resource requires Coder v2.24.0 https://github.com/coder/coder/releases/tag/v2.24.0 or later. --- # coder_ai_task (Resource) Use this resource to define Coder tasks. +~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later. + diff --git a/provider/ai_task.go b/provider/ai_task.go index 76b19f3..dd446dc 100644 --- a/provider/ai_task.go +++ b/provider/ai_task.go @@ -25,7 +25,7 @@ func aiTask() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this resource to define Coder tasks.", + Description: "Use this resource to define Coder tasks.\n\n~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.", CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics { resourceData.SetId(uuid.NewString()) return nil From 2b138afea23a657ef64d9a09c30e03a9d5ca333c Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 15:17:48 +0000 Subject: [PATCH 02/13] feat: implement automated version documentation system Implements a maintainable system for documenting minimum Coder version requirements for each resource and data source. Changes: - Add resource_versions.go with version registry that developers must update - Modify docsgen to automatically inject version information into docs - Add version compatibility matrix to provider index page - Add developer documentation for maintaining version requirements - All resources now show their minimum required Coder version This ensures users can easily identify version requirements and prevents compatibility issues. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/data-sources/external_auth.md | 2 + docs/data-sources/parameter.md | 2 + docs/data-sources/provisioner.md | 2 + docs/data-sources/workspace.md | 2 + docs/data-sources/workspace_owner.md | 2 + docs/data-sources/workspace_preset.md | 2 + docs/data-sources/workspace_tags.md | 2 + docs/index.md | 14 ++++ docs/resources/agent.md | 2 + docs/resources/agent_instance.md | 2 + docs/resources/app.md | 2 + docs/resources/devcontainer.md | 2 + docs/resources/env.md | 2 + docs/resources/metadata.md | 2 + docs/resources/script.md | 2 + provider/RESOURCE_VERSIONS.md | 50 +++++++++++++ provider/resource_versions.go | 33 +++++++++ scripts/docsgen/main.go | 101 +++++++++++++++++++++++++- templates/index.md.tmpl | 14 ++++ 19 files changed, 239 insertions(+), 1 deletion(-) create mode 100644 provider/RESOURCE_VERSIONS.md create mode 100644 provider/resource_versions.go diff --git a/docs/data-sources/external_auth.md b/docs/data-sources/external_auth.md index e4089f2..b98c0eb 100644 --- a/docs/data-sources/external_auth.md +++ b/docs/data-sources/external_auth.md @@ -10,6 +10,8 @@ description: |- Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md index ecba392..d9ae02e 100644 --- a/docs/data-sources/parameter.md +++ b/docs/data-sources/parameter.md @@ -10,6 +10,8 @@ description: |- Use this data source to configure editable options for workspaces. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/provisioner.md b/docs/data-sources/provisioner.md index ba930a2..64fb83b 100644 --- a/docs/data-sources/provisioner.md +++ b/docs/data-sources/provisioner.md @@ -10,6 +10,8 @@ description: |- Use this data source to get information about the Coder provisioner. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/workspace.md b/docs/data-sources/workspace.md index 4dacdfc..705ed2c 100644 --- a/docs/data-sources/workspace.md +++ b/docs/data-sources/workspace.md @@ -10,6 +10,8 @@ description: |- Use this data source to get information for the active workspace build. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/workspace_owner.md b/docs/data-sources/workspace_owner.md index 2a912e1..ec54c7e 100644 --- a/docs/data-sources/workspace_owner.md +++ b/docs/data-sources/workspace_owner.md @@ -10,6 +10,8 @@ description: |- Use this data source to fetch information about the workspace owner. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md index 6905740..3fb79a3 100644 --- a/docs/data-sources/workspace_preset.md +++ b/docs/data-sources/workspace_preset.md @@ -10,6 +10,8 @@ description: |- Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/data-sources/workspace_tags.md b/docs/data-sources/workspace_tags.md index 010adfe..ce2cb53 100644 --- a/docs/data-sources/workspace_tags.md +++ b/docs/data-sources/workspace_tags.md @@ -10,6 +10,8 @@ description: |- Use this data source to configure workspace tags to select provisioners. +~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/index.md b/docs/index.md index c30f147..cd46104 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. +## Version Compatibility + +The following table shows the minimum Coder version required for each terraform-provider-coder release: + +| Provider Version | Minimum Coder Version | Key Features | +|------------------|-----------------------|--------------| +| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support | +| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource | +| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds | +| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support | +| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider | + +~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. + ## Example ```terraform diff --git a/docs/resources/agent.md b/docs/resources/agent.md index 87ab423..03202f6 100644 --- a/docs/resources/agent.md +++ b/docs/resources/agent.md @@ -10,6 +10,8 @@ description: |- Use this resource to associate an agent. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/resources/agent_instance.md b/docs/resources/agent_instance.md index ec855b1..48f3ae2 100644 --- a/docs/resources/agent_instance.md +++ b/docs/resources/agent_instance.md @@ -10,6 +10,8 @@ description: |- Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/resources/app.md b/docs/resources/app.md index 6be99cf..15075ad 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -10,6 +10,8 @@ description: |- Use this resource to define shortcuts to access applications in a workspace. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index 06d7f6f..a3d4019 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -11,6 +11,8 @@ description: |- Define a Dev Container the agent should know of and attempt to autostart. +~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. + -> This resource is only available in Coder v2.21 and later. diff --git a/docs/resources/env.md b/docs/resources/env.md index 3a5a7f3..b39f0ca 100644 --- a/docs/resources/env.md +++ b/docs/resources/env.md @@ -10,6 +10,8 @@ description: |- Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md index d8329ea..b753350 100644 --- a/docs/resources/metadata.md +++ b/docs/resources/metadata.md @@ -11,6 +11,8 @@ description: |- Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. ## Example Usage diff --git a/docs/resources/script.md b/docs/resources/script.md index 21bfaec..68c1668 100644 --- a/docs/resources/script.md +++ b/docs/resources/script.md @@ -10,6 +10,8 @@ description: |- Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. +~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + ## Example Usage ```terraform diff --git a/provider/RESOURCE_VERSIONS.md b/provider/RESOURCE_VERSIONS.md new file mode 100644 index 0000000..8efdc60 --- /dev/null +++ b/provider/RESOURCE_VERSIONS.md @@ -0,0 +1,50 @@ +# Resource Version Requirements + +This document explains how to maintain version requirements for terraform-provider-coder resources. + +## Overview + +The `resource_versions.go` file contains a registry of minimum Coder version requirements for each resource and data source. This information is automatically injected into the documentation during the build process. + +## Adding a New Resource + +When adding a new resource or data source, you MUST: + +1. Add an entry to the `ResourceVersions` map in `resource_versions.go` +2. Set the minimum Coder version that supports this resource +3. Run `make gen` to regenerate the documentation + +### Example + +```go +var ResourceVersions = map[string]string{ + // ... existing entries ... + "coder_new_resource": "v2.25.0", // Add your new resource here +} +``` + +## Version Guidelines + +- **Default minimum**: v2.18.0 (the base requirement for terraform-provider-coder v2.0+) +- **New features**: Use the Coder version where the feature was first introduced +- **Attribute-level requirements**: Use the `AttributeVersions` map for attributes added after the resource itself + +## How It Works + +1. `terraform-plugin-docs` generates the initial documentation +2. Our custom `docsgen` script reads the version registry +3. Version notes are automatically added to each resource's documentation +4. The version compatibility matrix in `index.md` is maintained manually in the template + +## Testing + +After adding or updating version information: + +1. Run `make gen` +2. Check that the generated docs include the version note +3. Verify the note appears after the resource description + +## Common Issues + +- **Missing version error**: If you see "no version information found", add the resource to `ResourceVersions` +- **Duplicate notes**: If a resource already has version info in its Description, remove it and rely on the registry diff --git a/provider/resource_versions.go b/provider/resource_versions.go new file mode 100644 index 0000000..a63efb9 --- /dev/null +++ b/provider/resource_versions.go @@ -0,0 +1,33 @@ +package provider + +// ResourceVersions maps each resource and data source to its minimum required Coder version. +// IMPORTANT: When adding a new resource or data source, you MUST add an entry here! +// This ensures proper documentation of version requirements for users. +var ResourceVersions = map[string]string{ + // Resources + "coder_agent": "v2.18.0", // Base requirement for terraform-provider-coder v2.0+ + "coder_agent_instance": "v2.18.0", + "coder_ai_task": "v2.24.0", // AI features introduced in v2.24.0 + "coder_app": "v2.18.0", + "coder_devcontainer": "v2.21.0", // Devcontainer support added in v2.21.0 + "coder_env": "v2.18.0", + "coder_metadata": "v2.18.0", + "coder_script": "v2.18.0", + + // Data Sources + "coder_external_auth": "v2.18.0", + "coder_parameter": "v2.18.0", + "coder_provisioner": "v2.18.0", + "coder_workspace": "v2.18.0", + "coder_workspace_owner": "v2.18.0", + "coder_workspace_preset": "v2.18.0", + "coder_workspace_tags": "v2.18.0", +} + +// AttributeVersions maps specific resource attributes to their minimum required Coder version. +// Use this for attributes that were added after the resource itself. +var AttributeVersions = map[string]map[string]string{ + "coder_app": { + "hidden": "v2.16.0", // Hidden attribute added in v2.16.0 + }, +} diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index 53b43ca..97189e6 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -14,7 +14,9 @@ import ( "golang.org/x/xerrors" ) -// This script patches Markdown docs generated by `terraform-plugin-docs` to expose the original deprecation message. +// This script patches Markdown docs generated by `terraform-plugin-docs` to: +// 1. Expose the original deprecation message +// 2. Add minimum Coder version requirements const docsDir = "docs" // FIXME expose as flag? @@ -26,6 +28,12 @@ func main() { if err != nil { log.Fatal(err) } + + // Add version information to all resources and data sources + err = addVersionInformation(p) + if err != nil { + log.Fatal(err) + } } func exposeDeprecationMessage(p *schema.Provider) error { @@ -87,3 +95,94 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by return bytes.Replace(m, []byte("Deprecated"), []byte(fmt.Sprintf("**Deprecated**: %s", sch.Deprecated)), 1) }) } + +func addVersionInformation(p *schema.Provider) error { + // Add version info to data sources + for dataSourceName := range p.DataSourcesMap { + docFile := filepath.Join(docsDir, "data-sources", strings.Replace(dataSourceName, "coder_", "", 1)+".md") + if err := addVersionToDoc(docFile, dataSourceName); err != nil { + return xerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w", dataSourceName, err) + } + } + + // Add version info to resources + for resourceName := range p.ResourcesMap { + docFile := filepath.Join(docsDir, "resources", strings.Replace(resourceName, "coder_", "", 1)+".md") + if err := addVersionToDoc(docFile, resourceName); err != nil { + return xerrors.Errorf("unable to add version to resource doc file (resource: %s): %w", resourceName, err) + } + } + + return nil +} + +func addVersionToDoc(docPath string, resourceName string) error { + version, ok := provider.ResourceVersions[resourceName] + if !ok { + return xerrors.Errorf("no version information found for %s. Please add it to provider.ResourceVersions", resourceName) + } + + doc, err := os.ReadFile(docPath) + if err != nil { + return xerrors.Errorf("can't read the doc file: %w", err) + } + + docStr := string(doc) + + // Check if version note already exists + if strings.Contains(docStr, "~> **Note:** This") && strings.Contains(docStr, "requires") && strings.Contains(docStr, "Coder") { + // Version note already exists, skip + return nil + } + + // Add version note after the description + versionNote := fmt.Sprintf("\n\n~> **Note:** This %s requires [Coder %s](https://github.com/coder/coder/releases/tag/%s) or later.", + getResourceType(resourceName), version, version) + + // Find the end of frontmatter + frontmatterEnd := -1 + lines := strings.Split(docStr, "\n") + + if len(lines) > 0 && lines[0] == "---" { + for i := 1; i < len(lines); i++ { + if lines[i] == "---" { + frontmatterEnd = i + break + } + } + } + + // Find where to insert the version note + inserted := false + for i := frontmatterEnd + 1; i < len(lines); i++ { + // Skip empty lines and headings + if lines[i] == "" || strings.HasPrefix(lines[i], "#") { + continue + } + + // Insert after the first paragraph (non-empty, non-heading line) + lines[i] = lines[i] + versionNote + inserted = true + break + } + + if !inserted { + // If we couldn't find a good place, add it at the end + lines = append(lines, versionNote) + } + + docStr = strings.Join(lines, "\n") + + err = os.WriteFile(docPath, []byte(docStr), 0644) + if err != nil { + return xerrors.Errorf("can't write modified doc file: %w", err) + } + return nil +} + +func getResourceType(name string) string { + if strings.Contains(name, "data_source") || strings.Contains(name, "workspace") || strings.Contains(name, "provisioner") || strings.Contains(name, "parameter") || strings.Contains(name, "external_auth") { + return "data source" + } + return "resource" +} diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index efdaae9..aebe5ac 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -14,6 +14,20 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. +## Version Compatibility + +The following table shows the minimum Coder version required for each terraform-provider-coder release: + +| Provider Version | Minimum Coder Version | Key Features | +|------------------|-----------------------|--------------| +| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support | +| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource | +| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds | +| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support | +| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider | + +~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. + ## Example {{tffile "examples/provider/provider.tf"}} From 14601f864dd8020887596f9af10b3ad815e56f42 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 15:39:51 +0000 Subject: [PATCH 03/13] refactor: implement inline version metadata system Refactored the version documentation system to store version requirements directly in resource and attribute descriptions, eliminating the need for an external registry file. Changes: - Removed external resource_versions.go registry - Added version metadata markers in descriptions (@minCoderVersion, @since) - Enhanced docsgen to extract and format version information - Added inline version markers for attributes with non-default versions - Created developer documentation for the new system This approach keeps version information close to the code, making it easier to maintain and harder to forget when adding new features. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/resources/ai_task.md | 5 +- docs/resources/app.md | 2 +- docs/resources/devcontainer.md | 7 +- provider/RESOURCE_VERSIONS.md | 50 ----------- provider/VERSION_METADATA.md | 104 +++++++++++++++++++++++ provider/ai_task.go | 2 +- provider/app.go | 2 +- provider/devcontainer.go | 2 +- provider/resource_versions.go | 33 -------- provider/version_meta.go | 26 ++++++ scripts/docsgen/main.go | 147 ++++++++++++++++++++++++++++----- 11 files changed, 265 insertions(+), 115 deletions(-) delete mode 100644 provider/RESOURCE_VERSIONS.md create mode 100644 provider/VERSION_METADATA.md delete mode 100644 provider/resource_versions.go create mode 100644 provider/version_meta.go diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index 30d7eba..24ba905 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -3,13 +3,12 @@ page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- - Use this resource to define Coder tasks. - ~> Note: This resource requires Coder v2.24.0 https://github.com/coder/coder/releases/tag/v2.24.0 or later. + Use this resource to define Coder tasks. @minCoderVersion:v2.24.0 --- # coder_ai_task (Resource) -Use this resource to define Coder tasks. +Use this resource to define Coder tasks. @minCoderVersion:v2.24.0 ~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later. diff --git a/docs/resources/app.md b/docs/resources/app.md index 15075ad..57f6d7e 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -67,7 +67,7 @@ resource "coder_app" "vim" { - `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. - `group` (String) The name of a group that this app belongs to. - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) -- `hidden` (Boolean) Determines if the app is visible in the UI (minimum Coder version: v2.16). +- `hidden` (Boolean) Determines if the app is visible in the UI. *(since v2.16.0)* - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index a3d4019..202568d 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -3,18 +3,15 @@ page_title: "coder_devcontainer Resource - terraform-provider-coder" subcategory: "" description: |- - Define a Dev Container the agent should know of and attempt to autostart. - -> This resource is only available in Coder v2.21 and later. + Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0 --- # coder_devcontainer (Resource) -Define a Dev Container the agent should know of and attempt to autostart. +Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0 ~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. --> This resource is only available in Coder v2.21 and later. - diff --git a/provider/RESOURCE_VERSIONS.md b/provider/RESOURCE_VERSIONS.md deleted file mode 100644 index 8efdc60..0000000 --- a/provider/RESOURCE_VERSIONS.md +++ /dev/null @@ -1,50 +0,0 @@ -# Resource Version Requirements - -This document explains how to maintain version requirements for terraform-provider-coder resources. - -## Overview - -The `resource_versions.go` file contains a registry of minimum Coder version requirements for each resource and data source. This information is automatically injected into the documentation during the build process. - -## Adding a New Resource - -When adding a new resource or data source, you MUST: - -1. Add an entry to the `ResourceVersions` map in `resource_versions.go` -2. Set the minimum Coder version that supports this resource -3. Run `make gen` to regenerate the documentation - -### Example - -```go -var ResourceVersions = map[string]string{ - // ... existing entries ... - "coder_new_resource": "v2.25.0", // Add your new resource here -} -``` - -## Version Guidelines - -- **Default minimum**: v2.18.0 (the base requirement for terraform-provider-coder v2.0+) -- **New features**: Use the Coder version where the feature was first introduced -- **Attribute-level requirements**: Use the `AttributeVersions` map for attributes added after the resource itself - -## How It Works - -1. `terraform-plugin-docs` generates the initial documentation -2. Our custom `docsgen` script reads the version registry -3. Version notes are automatically added to each resource's documentation -4. The version compatibility matrix in `index.md` is maintained manually in the template - -## Testing - -After adding or updating version information: - -1. Run `make gen` -2. Check that the generated docs include the version note -3. Verify the note appears after the resource description - -## Common Issues - -- **Missing version error**: If you see "no version information found", add the resource to `ResourceVersions` -- **Duplicate notes**: If a resource already has version info in its Description, remove it and rely on the registry diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md new file mode 100644 index 0000000..4107821 --- /dev/null +++ b/provider/VERSION_METADATA.md @@ -0,0 +1,104 @@ +# Version Metadata Documentation + +This document explains how to add version requirements to resources and attributes in the terraform-provider-coder. + +## Overview + +Version information is embedded directly in resource and attribute descriptions using special markers. The documentation generation process automatically extracts this information and formats it appropriately. + +## Adding Version Requirements + +### For Resources + +Add a version marker to the resource's `Description` field: + +```go +Description: "Your resource description. @minCoderVersion:v2.21.0", +``` + +The marker will be automatically removed from the generated docs and replaced with a formatted note. + +### For Attributes + +Add a version marker to the attribute's `Description` field: + +```go +"my_attribute": { + Type: schema.TypeString, + Description: "Attribute description. @since:v2.16.0", + Optional: true, +}, +``` + +This will result in the documentation showing: `- my_attribute (String) Attribute description. *(since v2.16.0)*` + +## Version Marker Formats + +You can use either format: +- `@minCoderVersion:vX.Y.Z` - For resources +- `@since:vX.Y.Z` - For attributes + +Both formats are recognized and processed the same way. + +## How It Works + +1. **During Development**: Add version markers to descriptions +2. **During Doc Generation**: + - `terraform-plugin-docs` generates initial documentation + - Our custom `docsgen` script: + - Extracts version information from descriptions + - Adds formatted version notes to resources + - Adds inline version markers to attributes + - Cleans up the version patterns from descriptions + +## Examples + +### Resource Example + +```go +func myNewResource() *schema.Resource { + return &schema.Resource{ + Description: "Manages a new Coder feature. @minCoderVersion:v2.25.0", + // ... rest of resource definition + } +} +``` + +Results in documentation with: +```markdown +# coder_my_new (Resource) + +Manages a new Coder feature. + +~> **Note:** This resource requires [Coder v2.25.0](https://github.com/coder/coder/releases/tag/v2.25.0) or later. +``` + +### Attribute Example + +```go +"advanced_option": { + Type: schema.TypeBool, + Description: "Enable advanced features. @since:v2.22.0", + Optional: true, +}, +``` + +Results in documentation with: +```markdown +- `advanced_option` (Boolean) Enable advanced features. *(since v2.22.0)* +``` + +## Default Versions + +- Resources without version markers default to `v2.18.0` (the base requirement) +- Attributes without version markers don't show version information +- Special resources have hardcoded defaults: + - `coder_devcontainer`: v2.21.0 + - `coder_ai_task`: v2.24.0 + +## Best Practices + +1. **Always add version markers** when creating new resources or attributes +2. **Use semantic versioning** (vX.Y.Z format) +3. **Test documentation generation** with `make gen` after adding markers +4. **Keep descriptions concise** - the version marker is removed from the final docs diff --git a/provider/ai_task.go b/provider/ai_task.go index dd446dc..17ff238 100644 --- a/provider/ai_task.go +++ b/provider/ai_task.go @@ -25,7 +25,7 @@ func aiTask() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this resource to define Coder tasks.\n\n~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later.", + Description: "Use this resource to define Coder tasks. @minCoderVersion:v2.24.0", CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics { resourceData.SetId(uuid.NewString()) return nil diff --git a/provider/app.go b/provider/app.go index adbbf0e..18d788c 100644 --- a/provider/app.go +++ b/provider/app.go @@ -251,7 +251,7 @@ func appResource() *schema.Resource { }, "hidden": { Type: schema.TypeBool, - Description: "Determines if the app is visible in the UI (minimum Coder version: v2.16).", + Description: "Determines if the app is visible in the UI. @since:v2.16.0", Default: false, ForceNew: true, Optional: true, diff --git a/provider/devcontainer.go b/provider/devcontainer.go index 81a3119..8b4a2db 100644 --- a/provider/devcontainer.go +++ b/provider/devcontainer.go @@ -13,7 +13,7 @@ func devcontainerResource() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Define a Dev Container the agent should know of and attempt to autostart.\n\n-> This resource is only available in Coder v2.21 and later.", + Description: "Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0", CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics { rd.SetId(uuid.NewString()) diff --git a/provider/resource_versions.go b/provider/resource_versions.go deleted file mode 100644 index a63efb9..0000000 --- a/provider/resource_versions.go +++ /dev/null @@ -1,33 +0,0 @@ -package provider - -// ResourceVersions maps each resource and data source to its minimum required Coder version. -// IMPORTANT: When adding a new resource or data source, you MUST add an entry here! -// This ensures proper documentation of version requirements for users. -var ResourceVersions = map[string]string{ - // Resources - "coder_agent": "v2.18.0", // Base requirement for terraform-provider-coder v2.0+ - "coder_agent_instance": "v2.18.0", - "coder_ai_task": "v2.24.0", // AI features introduced in v2.24.0 - "coder_app": "v2.18.0", - "coder_devcontainer": "v2.21.0", // Devcontainer support added in v2.21.0 - "coder_env": "v2.18.0", - "coder_metadata": "v2.18.0", - "coder_script": "v2.18.0", - - // Data Sources - "coder_external_auth": "v2.18.0", - "coder_parameter": "v2.18.0", - "coder_provisioner": "v2.18.0", - "coder_workspace": "v2.18.0", - "coder_workspace_owner": "v2.18.0", - "coder_workspace_preset": "v2.18.0", - "coder_workspace_tags": "v2.18.0", -} - -// AttributeVersions maps specific resource attributes to their minimum required Coder version. -// Use this for attributes that were added after the resource itself. -var AttributeVersions = map[string]map[string]string{ - "coder_app": { - "hidden": "v2.16.0", // Hidden attribute added in v2.16.0 - }, -} diff --git a/provider/version_meta.go b/provider/version_meta.go new file mode 100644 index 0000000..c3d8489 --- /dev/null +++ b/provider/version_meta.go @@ -0,0 +1,26 @@ +package provider + +// VersionMeta provides utilities for managing version metadata in resources. +// Resources and attributes can specify their minimum Coder version requirements +// using these utilities. + +// MinCoderVersion is a helper function that returns a formatted version string +// for use in resource descriptions. This ensures consistent formatting. +func MinCoderVersion(version string) string { + return "@minCoderVersion:" + version +} + +// Common version constants for frequently used versions +const ( + // V2_18_0 is the base requirement for terraform-provider-coder v2.0+ + V2_18_0 = "v2.18.0" + + // V2_16_0 introduced the hidden attribute for apps + V2_16_0 = "v2.16.0" + + // V2_21_0 introduced devcontainer support + V2_21_0 = "v2.21.0" + + // V2_24_0 introduced AI task resources + V2_24_0 = "v2.24.0" +) diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index 97189e6..e01b816 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -16,11 +16,18 @@ import ( // This script patches Markdown docs generated by `terraform-plugin-docs` to: // 1. Expose the original deprecation message -// 2. Add minimum Coder version requirements +// 2. Extract and format version information from resource/attribute descriptions +// 3. Add inline version markers for attributes with version requirements const docsDir = "docs" // FIXME expose as flag? -var reDeprecatedProperty = regexp.MustCompile("`([^`]+)` \\(([^,\\)]+), Deprecated\\) ([^\n]+)") +var ( + reDeprecatedProperty = regexp.MustCompile("`([^`]+)` \\(([^,\\)]+), Deprecated\\) ([^\n]+)") + // Pattern to extract version info from descriptions: @minCoderVersion:v2.16.0 or @since:v2.16.0 + reVersionPattern = regexp.MustCompile(`@(?:minCoderVersion|since):(v\d+\.\d+\.\d+)`) + // Pattern to find existing version info in descriptions (to clean up) + reExistingVersionInfo = regexp.MustCompile(`\s*\(@(?:minCoderVersion|since):[^)]+\)|\s*\(minimum Coder version:[^)]+\)`) +) func main() { p := provider.New() @@ -29,8 +36,8 @@ func main() { log.Fatal(err) } - // Add version information to all resources and data sources - err = addVersionInformation(p) + // Process version information for all resources and data sources + err = processVersionInformation(p) if err != nil { log.Fatal(err) } @@ -96,32 +103,68 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by }) } -func addVersionInformation(p *schema.Provider) error { - // Add version info to data sources - for dataSourceName := range p.DataSourcesMap { +func processVersionInformation(p *schema.Provider) error { + // Process data sources + for dataSourceName, dataSource := range p.DataSourcesMap { docFile := filepath.Join(docsDir, "data-sources", strings.Replace(dataSourceName, "coder_", "", 1)+".md") - if err := addVersionToDoc(docFile, dataSourceName); err != nil { + + // Extract version from description + version := extractVersionFromDescription(dataSource.Description) + if version == "" { + // Default to v2.18.0 if no version specified + version = "v2.18.0" + } + + if err := addVersionToResourceDoc(docFile, dataSourceName, version, "data source"); err != nil { return xerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w", dataSourceName, err) } + + // Process attributes for version info + if err := processAttributeVersions(docFile, dataSource.Schema); err != nil { + return xerrors.Errorf("unable to process attribute versions for data-source (data-source: %s): %w", dataSourceName, err) + } } - // Add version info to resources - for resourceName := range p.ResourcesMap { + // Process resources + for resourceName, resource := range p.ResourcesMap { docFile := filepath.Join(docsDir, "resources", strings.Replace(resourceName, "coder_", "", 1)+".md") - if err := addVersionToDoc(docFile, resourceName); err != nil { + + // Extract version from description + version := extractVersionFromDescription(resource.Description) + if version == "" { + // Check for special cases + switch resourceName { + case "coder_devcontainer": + version = "v2.21.0" + case "coder_ai_task": + version = "v2.24.0" + default: + version = "v2.18.0" + } + } + + if err := addVersionToResourceDoc(docFile, resourceName, version, "resource"); err != nil { return xerrors.Errorf("unable to add version to resource doc file (resource: %s): %w", resourceName, err) } + + // Process attributes for version info + if err := processAttributeVersions(docFile, resource.Schema); err != nil { + return xerrors.Errorf("unable to process attribute versions for resource (resource: %s): %w", resourceName, err) + } } return nil } -func addVersionToDoc(docPath string, resourceName string) error { - version, ok := provider.ResourceVersions[resourceName] - if !ok { - return xerrors.Errorf("no version information found for %s. Please add it to provider.ResourceVersions", resourceName) +func extractVersionFromDescription(description string) string { + matches := reVersionPattern.FindStringSubmatch(description) + if len(matches) > 1 { + return matches[1] } + return "" +} +func addVersionToResourceDoc(docPath string, resourceName string, version string, resourceType string) error { doc, err := os.ReadFile(docPath) if err != nil { return xerrors.Errorf("can't read the doc file: %w", err) @@ -137,7 +180,7 @@ func addVersionToDoc(docPath string, resourceName string) error { // Add version note after the description versionNote := fmt.Sprintf("\n\n~> **Note:** This %s requires [Coder %s](https://github.com/coder/coder/releases/tag/%s) or later.", - getResourceType(resourceName), version, version) + resourceType, version, version) // Find the end of frontmatter frontmatterEnd := -1 @@ -180,9 +223,73 @@ func addVersionToDoc(docPath string, resourceName string) error { return nil } -func getResourceType(name string) string { - if strings.Contains(name, "data_source") || strings.Contains(name, "workspace") || strings.Contains(name, "provisioner") || strings.Contains(name, "parameter") || strings.Contains(name, "external_auth") { - return "data source" +func processAttributeVersions(docPath string, schemas map[string]*schema.Schema) error { + doc, err := os.ReadFile(docPath) + if err != nil { + return xerrors.Errorf("can't read the doc file: %w", err) } - return "resource" + + docStr := string(doc) + modified := false + + // Process each attribute that has version information + for attrName, attrSchema := range schemas { + version := extractVersionFromDescription(attrSchema.Description) + if version != "" && version != "v2.18.0" { // Only add version markers for non-default versions + // Clean the version pattern from the description in the docs + cleanDesc := reExistingVersionInfo.ReplaceAllString(attrSchema.Description, "") + cleanDesc = reVersionPattern.ReplaceAllString(cleanDesc, "") + + // Find the attribute in the documentation and add version marker + // Look for patterns like "- `attrName` (Type) Description" + attrPattern := regexp.MustCompile(fmt.Sprintf(`- \x60%s\x60 \([^)]+\) ([^\n]+)`, regexp.QuoteMeta(attrName))) + + newDocStr := attrPattern.ReplaceAllStringFunc(docStr, func(match string) string { + // Check if version marker already exists + if strings.Contains(match, "*(since") { + return match + } + // Clean version patterns from the description + cleanMatch := reVersionPattern.ReplaceAllString(match, "") + cleanMatch = reExistingVersionInfo.ReplaceAllString(cleanMatch, "") + // Add version marker at the end + return strings.TrimRight(cleanMatch, " ") + fmt.Sprintf(" *(since %s)*", version) + }) + + if newDocStr != docStr { + docStr = newDocStr + modified = true + } + + // Also handle nested attributes (e.g., in blocks) + // Look for patterns like " - `attrName` (Type) Description" (with more spaces) + nestedAttrPattern := regexp.MustCompile(fmt.Sprintf(`( +)- \x60%s\x60 \([^)]+\) ([^\n]+)`, regexp.QuoteMeta(attrName))) + + newDocStr = nestedAttrPattern.ReplaceAllStringFunc(docStr, func(match string) string { + // Check if version marker already exists + if strings.Contains(match, "*(since") { + return match + } + // Clean version patterns from the description + cleanMatch := reVersionPattern.ReplaceAllString(match, "") + cleanMatch = reExistingVersionInfo.ReplaceAllString(cleanMatch, "") + // Add version marker at the end + return strings.TrimRight(cleanMatch, " ") + fmt.Sprintf(" *(since %s)*", version) + }) + + if newDocStr != docStr { + docStr = newDocStr + modified = true + } + } + } + + if modified { + err = os.WriteFile(docPath, []byte(docStr), 0644) + if err != nil { + return xerrors.Errorf("can't write modified doc file: %w", err) + } + } + + return nil } From 898c99dae9b687a69d8030024da6f9d8c36688b8 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 15:50:36 +0000 Subject: [PATCH 04/13] refactor: standardize on single @since: version format Simplified the version metadata system to use a single @since: format for both resources and attributes, eliminating confusion from having two different formats. Changes: - Updated all @minCoderVersion: markers to @since: - Updated docsgen to only recognize @since: format - Simplified version_meta.go - Updated documentation to reflect single format This makes the system more consistent and easier to use. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/resources/ai_task.md | 4 ++-- docs/resources/devcontainer.md | 4 ++-- provider/VERSION_METADATA.md | 30 ++++++++++++++++-------------- provider/ai_task.go | 2 +- provider/devcontainer.go | 2 +- provider/version_meta.go | 10 ++-------- scripts/docsgen/main.go | 6 +++--- 7 files changed, 27 insertions(+), 31 deletions(-) diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index 24ba905..d92bab0 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -3,12 +3,12 @@ page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- - Use this resource to define Coder tasks. @minCoderVersion:v2.24.0 + Use this resource to define Coder tasks. @since:v2.24.0 --- # coder_ai_task (Resource) -Use this resource to define Coder tasks. @minCoderVersion:v2.24.0 +Use this resource to define Coder tasks. @since:v2.24.0 ~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later. diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index 202568d..f0b4dfc 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -3,12 +3,12 @@ page_title: "coder_devcontainer Resource - terraform-provider-coder" subcategory: "" description: |- - Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0 + Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0 --- # coder_devcontainer (Resource) -Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0 +Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0 ~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md index 4107821..0aa975d 100644 --- a/provider/VERSION_METADATA.md +++ b/provider/VERSION_METADATA.md @@ -4,23 +4,23 @@ This document explains how to add version requirements to resources and attribut ## Overview -Version information is embedded directly in resource and attribute descriptions using special markers. The documentation generation process automatically extracts this information and formats it appropriately. +Version information is embedded directly in resource and attribute descriptions using the `@since:` marker. The documentation generation process automatically extracts this information and formats it appropriately. ## Adding Version Requirements ### For Resources -Add a version marker to the resource's `Description` field: +Add a `@since:` marker to the resource's `Description` field: ```go -Description: "Your resource description. @minCoderVersion:v2.21.0", +Description: "Your resource description. @since:v2.21.0", ``` The marker will be automatically removed from the generated docs and replaced with a formatted note. ### For Attributes -Add a version marker to the attribute's `Description` field: +Add a `@since:` marker to the attribute's `Description` field: ```go "my_attribute": { @@ -32,17 +32,15 @@ Add a version marker to the attribute's `Description` field: This will result in the documentation showing: `- my_attribute (String) Attribute description. *(since v2.16.0)*` -## Version Marker Formats +## Version Marker Format -You can use either format: -- `@minCoderVersion:vX.Y.Z` - For resources -- `@since:vX.Y.Z` - For attributes +Use the format: `@since:vX.Y.Z` -Both formats are recognized and processed the same way. +This single format is used for both resources and attributes to maintain consistency. ## How It Works -1. **During Development**: Add version markers to descriptions +1. **During Development**: Add `@since:` markers to descriptions 2. **During Doc Generation**: - `terraform-plugin-docs` generates initial documentation - Our custom `docsgen` script: @@ -58,7 +56,7 @@ Both formats are recognized and processed the same way. ```go func myNewResource() *schema.Resource { return &schema.Resource{ - Description: "Manages a new Coder feature. @minCoderVersion:v2.25.0", + Description: "Manages a new Coder feature. @since:v2.25.0", // ... rest of resource definition } } @@ -90,15 +88,19 @@ Results in documentation with: ## Default Versions -- Resources without version markers default to `v2.18.0` (the base requirement) -- Attributes without version markers don't show version information +- Resources without `@since:` markers default to `v2.18.0` (the base requirement) +- Attributes without `@since:` markers don't show version information - Special resources have hardcoded defaults: - `coder_devcontainer`: v2.21.0 - `coder_ai_task`: v2.24.0 ## Best Practices -1. **Always add version markers** when creating new resources or attributes +1. **Always add @since: markers** when creating new resources or attributes 2. **Use semantic versioning** (vX.Y.Z format) 3. **Test documentation generation** with `make gen` after adding markers 4. **Keep descriptions concise** - the version marker is removed from the final docs +5. **Use the version constants** from `version_meta.go` when available: + ```go + Description: "My feature. @since:" + provider.V2_21_0, + ``` diff --git a/provider/ai_task.go b/provider/ai_task.go index 17ff238..22bf376 100644 --- a/provider/ai_task.go +++ b/provider/ai_task.go @@ -25,7 +25,7 @@ func aiTask() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this resource to define Coder tasks. @minCoderVersion:v2.24.0", + Description: "Use this resource to define Coder tasks. @since:v2.24.0", CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics { resourceData.SetId(uuid.NewString()) return nil diff --git a/provider/devcontainer.go b/provider/devcontainer.go index 8b4a2db..d3b8101 100644 --- a/provider/devcontainer.go +++ b/provider/devcontainer.go @@ -13,7 +13,7 @@ func devcontainerResource() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Define a Dev Container the agent should know of and attempt to autostart. @minCoderVersion:v2.21.0", + Description: "Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0", CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics { rd.SetId(uuid.NewString()) diff --git a/provider/version_meta.go b/provider/version_meta.go index c3d8489..6811d2e 100644 --- a/provider/version_meta.go +++ b/provider/version_meta.go @@ -1,14 +1,8 @@ package provider -// VersionMeta provides utilities for managing version metadata in resources. +// VersionMeta provides utilities and constants for managing version metadata in resources. // Resources and attributes can specify their minimum Coder version requirements -// using these utilities. - -// MinCoderVersion is a helper function that returns a formatted version string -// for use in resource descriptions. This ensures consistent formatting. -func MinCoderVersion(version string) string { - return "@minCoderVersion:" + version -} +// using the @since: marker in their descriptions. // Common version constants for frequently used versions const ( diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index e01b816..cedefc4 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -23,10 +23,10 @@ const docsDir = "docs" // FIXME expose as flag? var ( reDeprecatedProperty = regexp.MustCompile("`([^`]+)` \\(([^,\\)]+), Deprecated\\) ([^\n]+)") - // Pattern to extract version info from descriptions: @minCoderVersion:v2.16.0 or @since:v2.16.0 - reVersionPattern = regexp.MustCompile(`@(?:minCoderVersion|since):(v\d+\.\d+\.\d+)`) + // Pattern to extract version info from descriptions: @since:v2.16.0 + reVersionPattern = regexp.MustCompile(`@since:(v\d+\.\d+\.\d+)`) // Pattern to find existing version info in descriptions (to clean up) - reExistingVersionInfo = regexp.MustCompile(`\s*\(@(?:minCoderVersion|since):[^)]+\)|\s*\(minimum Coder version:[^)]+\)`) + reExistingVersionInfo = regexp.MustCompile(`\s*\(@since:[^)]+\)|\s*\(minimum Coder version:[^)]+\)`) ) func main() { From c35d3ddf423749f6df160495ee498730466934c6 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 16:06:38 +0000 Subject: [PATCH 05/13] refactor: only show version requirements for new resources Removed version requirements from resources that existed before Coder v2.0, as these requirements are not meaningful for established resources. Changes: - Updated docsgen to only add version notes when @since: marker is present - Removed default v2.18.0 version assignment - Added @since:v2.8.0 to workspace_preset data source - Updated documentation to clarify when to add version markers Now only resources/features introduced after v2.0 show version requirements: - coder_ai_task (v2.24.0) - coder_devcontainer (v2.21.0) - coder_workspace_preset (v2.8.0) - coder_app.hidden attribute (v2.16.0) Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/data-sources/external_auth.md | 2 -- docs/data-sources/parameter.md | 2 -- docs/data-sources/provisioner.md | 2 -- docs/data-sources/workspace.md | 2 -- docs/data-sources/workspace_owner.md | 2 -- docs/data-sources/workspace_preset.md | 6 +++--- docs/data-sources/workspace_tags.md | 2 -- docs/resources/agent.md | 2 -- docs/resources/agent_instance.md | 2 -- docs/resources/app.md | 2 -- docs/resources/env.md | 2 -- docs/resources/metadata.md | 2 -- docs/resources/script.md | 2 -- provider/VERSION_METADATA.md | 11 +++++----- provider/version_meta.go | 3 +++ provider/workspace_preset.go | 2 +- scripts/docsgen/main.go | 29 +++++++++------------------ 17 files changed, 21 insertions(+), 54 deletions(-) diff --git a/docs/data-sources/external_auth.md b/docs/data-sources/external_auth.md index b98c0eb..e4089f2 100644 --- a/docs/data-sources/external_auth.md +++ b/docs/data-sources/external_auth.md @@ -10,8 +10,6 @@ description: |- Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md index d9ae02e..ecba392 100644 --- a/docs/data-sources/parameter.md +++ b/docs/data-sources/parameter.md @@ -10,8 +10,6 @@ description: |- Use this data source to configure editable options for workspaces. -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/data-sources/provisioner.md b/docs/data-sources/provisioner.md index 64fb83b..ba930a2 100644 --- a/docs/data-sources/provisioner.md +++ b/docs/data-sources/provisioner.md @@ -10,8 +10,6 @@ description: |- Use this data source to get information about the Coder provisioner. -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/data-sources/workspace.md b/docs/data-sources/workspace.md index 705ed2c..4dacdfc 100644 --- a/docs/data-sources/workspace.md +++ b/docs/data-sources/workspace.md @@ -10,8 +10,6 @@ description: |- Use this data source to get information for the active workspace build. -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/data-sources/workspace_owner.md b/docs/data-sources/workspace_owner.md index ec54c7e..2a912e1 100644 --- a/docs/data-sources/workspace_owner.md +++ b/docs/data-sources/workspace_owner.md @@ -10,8 +10,6 @@ description: |- Use this data source to fetch information about the workspace owner. -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md index 3fb79a3..417c516 100644 --- a/docs/data-sources/workspace_preset.md +++ b/docs/data-sources/workspace_preset.md @@ -3,14 +3,14 @@ page_title: "coder_workspace_preset Data Source - terraform-provider-coder" subcategory: "" description: |- - Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. + Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0 --- # coder_workspace_preset (Data Source) -Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. +Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0 -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. +~> **Note:** This data source requires [Coder v2.8.0](https://github.com/coder/coder/releases/tag/v2.8.0) or later. ## Example Usage diff --git a/docs/data-sources/workspace_tags.md b/docs/data-sources/workspace_tags.md index ce2cb53..010adfe 100644 --- a/docs/data-sources/workspace_tags.md +++ b/docs/data-sources/workspace_tags.md @@ -10,8 +10,6 @@ description: |- Use this data source to configure workspace tags to select provisioners. -~> **Note:** This data source requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/resources/agent.md b/docs/resources/agent.md index 03202f6..87ab423 100644 --- a/docs/resources/agent.md +++ b/docs/resources/agent.md @@ -10,8 +10,6 @@ description: |- Use this resource to associate an agent. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/resources/agent_instance.md b/docs/resources/agent_instance.md index 48f3ae2..ec855b1 100644 --- a/docs/resources/agent_instance.md +++ b/docs/resources/agent_instance.md @@ -10,8 +10,6 @@ description: |- Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/resources/app.md b/docs/resources/app.md index 57f6d7e..6afbca6 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -10,8 +10,6 @@ description: |- Use this resource to define shortcuts to access applications in a workspace. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/resources/env.md b/docs/resources/env.md index b39f0ca..3a5a7f3 100644 --- a/docs/resources/env.md +++ b/docs/resources/env.md @@ -10,8 +10,6 @@ description: |- Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md index b753350..d8329ea 100644 --- a/docs/resources/metadata.md +++ b/docs/resources/metadata.md @@ -11,8 +11,6 @@ description: |- Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. ## Example Usage diff --git a/docs/resources/script.md b/docs/resources/script.md index 68c1668..21bfaec 100644 --- a/docs/resources/script.md +++ b/docs/resources/script.md @@ -10,8 +10,6 @@ description: |- Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. -~> **Note:** This resource requires [Coder v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - ## Example Usage ```terraform diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md index 0aa975d..3d5b396 100644 --- a/provider/VERSION_METADATA.md +++ b/provider/VERSION_METADATA.md @@ -86,13 +86,12 @@ Results in documentation with: - `advanced_option` (Boolean) Enable advanced features. *(since v2.22.0)* ``` -## Default Versions +## When to Add Version Information -- Resources without `@since:` markers default to `v2.18.0` (the base requirement) -- Attributes without `@since:` markers don't show version information -- Special resources have hardcoded defaults: - - `coder_devcontainer`: v2.21.0 - - `coder_ai_task`: v2.24.0 +- **Add @since: markers** for resources introduced after Coder v2.0 +- **Add @since: markers** for attributes added to existing resources +- **Don't add markers** for resources that existed before Coder v2.0 +- Resources and attributes without `@since:` markers won't show version information ## Best Practices diff --git a/provider/version_meta.go b/provider/version_meta.go index 6811d2e..05c36fb 100644 --- a/provider/version_meta.go +++ b/provider/version_meta.go @@ -17,4 +17,7 @@ const ( // V2_24_0 introduced AI task resources V2_24_0 = "v2.24.0" + + // V2_8_0 introduced workspace preset data source + V2_8_0 = "v2.8.0" ) diff --git a/provider/workspace_preset.go b/provider/workspace_preset.go index 1d7576e..f366999 100644 --- a/provider/workspace_preset.go +++ b/provider/workspace_preset.go @@ -58,7 +58,7 @@ func workspacePresetDataSource() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace.", + Description: "Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0", ReadContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics { var preset WorkspacePreset diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index cedefc4..c4c5f69 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -110,13 +110,11 @@ func processVersionInformation(p *schema.Provider) error { // Extract version from description version := extractVersionFromDescription(dataSource.Description) - if version == "" { - // Default to v2.18.0 if no version specified - version = "v2.18.0" - } - - if err := addVersionToResourceDoc(docFile, dataSourceName, version, "data source"); err != nil { - return xerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w", dataSourceName, err) + if version != "" { + // Only add version note if explicitly specified + if err := addVersionToResourceDoc(docFile, dataSourceName, version, "data source"); err != nil { + return xerrors.Errorf("unable to add version to data-source doc file (data-source: %s): %w", dataSourceName, err) + } } // Process attributes for version info @@ -131,22 +129,13 @@ func processVersionInformation(p *schema.Provider) error { // Extract version from description version := extractVersionFromDescription(resource.Description) - if version == "" { - // Check for special cases - switch resourceName { - case "coder_devcontainer": - version = "v2.21.0" - case "coder_ai_task": - version = "v2.24.0" - default: - version = "v2.18.0" + if version != "" { + // Only add version note if explicitly specified + if err := addVersionToResourceDoc(docFile, resourceName, version, "resource"); err != nil { + return xerrors.Errorf("unable to add version to resource doc file (resource: %s): %w", resourceName, err) } } - if err := addVersionToResourceDoc(docFile, resourceName, version, "resource"); err != nil { - return xerrors.Errorf("unable to add version to resource doc file (resource: %s): %w", resourceName, err) - } - // Process attributes for version info if err := processAttributeVersions(docFile, resource.Schema); err != nil { return xerrors.Errorf("unable to process attribute versions for resource (resource: %s): %w", resourceName, err) From 38d3b0e77aa53b53925c687c1e6aae24757b5d86 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 16:40:50 +0000 Subject: [PATCH 06/13] fix: remove @since marker from hidden attribute (added before provider v2.0) The hidden attribute for coder_app was added in September 2024, before terraform-provider-coder v2.0.1 was released in December 2024. Only resources/features added after provider v2.0 should have @since markers. Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- provider/app.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/provider/app.go b/provider/app.go index 18d788c..e59e4c2 100644 --- a/provider/app.go +++ b/provider/app.go @@ -251,7 +251,7 @@ func appResource() *schema.Resource { }, "hidden": { Type: schema.TypeBool, - Description: "Determines if the app is visible in the UI. @since:v2.16.0", + Description: "Determines if the app is visible in the UI.", Default: false, ForceNew: true, Optional: true, From 6b0d6784d44fd3e5151a41be5f84f1e78ade903d Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 16:44:11 +0000 Subject: [PATCH 07/13] docs: regenerate documentation after removing @since marker Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/resources/app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/app.md b/docs/resources/app.md index 6afbca6..cad082b 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -65,7 +65,7 @@ resource "coder_app" "vim" { - `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. - `group` (String) The name of a group that this app belongs to. - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) -- `hidden` (Boolean) Determines if the app is visible in the UI. *(since v2.16.0)* +- `hidden` (Boolean) Determines if the app is visible in the UI. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). From a6078d3604f0a1c012d9e5921fcf020165eb7b96 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:10:13 +0000 Subject: [PATCH 08/13] fix: address review feedback - Remove version compatibility table from index.md - Clean up ai_task description to remove @since marker - Clean up workspace_preset description to remove @since marker - Regenerate documentation Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/data-sources/workspace_preset.md | 6 ++---- docs/index.md | 10 +--------- docs/resources/ai_task.md | 6 ++---- provider/ai_task.go | 2 +- provider/workspace_preset.go | 2 +- templates/index.md.tmpl | 10 +--------- 6 files changed, 8 insertions(+), 28 deletions(-) diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md index 417c516..6905740 100644 --- a/docs/data-sources/workspace_preset.md +++ b/docs/data-sources/workspace_preset.md @@ -3,14 +3,12 @@ page_title: "coder_workspace_preset Data Source - terraform-provider-coder" subcategory: "" description: |- - Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0 + Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. --- # coder_workspace_preset (Data Source) -Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0 - -~> **Note:** This data source requires [Coder v2.8.0](https://github.com/coder/coder/releases/tag/v2.8.0) or later. +Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. ## Example Usage diff --git a/docs/index.md b/docs/index.md index cd46104..343ca8b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,15 +16,7 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t ## Version Compatibility -The following table shows the minimum Coder version required for each terraform-provider-coder release: - -| Provider Version | Minimum Coder Version | Key Features | -|------------------|-----------------------|--------------| -| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support | -| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource | -| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds | -| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support | -| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider | +This provider automatically documents version requirements for individual resources and features. ~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index d92bab0..1922ef5 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -3,14 +3,12 @@ page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- - Use this resource to define Coder tasks. @since:v2.24.0 + Use this resource to define Coder tasks. --- # coder_ai_task (Resource) -Use this resource to define Coder tasks. @since:v2.24.0 - -~> **Note:** This resource requires [Coder v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) or later. +Use this resource to define Coder tasks. diff --git a/provider/ai_task.go b/provider/ai_task.go index 22bf376..281b047 100644 --- a/provider/ai_task.go +++ b/provider/ai_task.go @@ -25,7 +25,7 @@ func aiTask() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this resource to define Coder tasks. @since:v2.24.0", + Description: "Use this resource to define Coder tasks.", CreateContext: func(c context.Context, resourceData *schema.ResourceData, i any) diag.Diagnostics { resourceData.SetId(uuid.NewString()) return nil diff --git a/provider/workspace_preset.go b/provider/workspace_preset.go index f366999..1d7576e 100644 --- a/provider/workspace_preset.go +++ b/provider/workspace_preset.go @@ -58,7 +58,7 @@ func workspacePresetDataSource() *schema.Resource { return &schema.Resource{ SchemaVersion: 1, - Description: "Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. @since:v2.8.0", + Description: "Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace.", ReadContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics { var preset WorkspacePreset diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index aebe5ac..d34dc25 100644 --- a/templates/index.md.tmpl +++ b/templates/index.md.tmpl @@ -16,15 +16,7 @@ Terraform provider for managing Coder [templates](https://coder.com/docs/admin/t ## Version Compatibility -The following table shows the minimum Coder version required for each terraform-provider-coder release: - -| Provider Version | Minimum Coder Version | Key Features | -|------------------|-----------------------|--------------| -| v2.8.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Default preset support | -| v2.7.0+ | [v2.24.0](https://github.com/coder/coder/releases/tag/v2.24.0) | AI task resource | -| v2.6.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Scheduling configuration for prebuilds | -| v2.5.0+ | [v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) | Devcontainer support | -| v2.0.0+ | [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) | Base requirement for v2 provider | +This provider automatically documents version requirements for individual resources and features. ~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. From 98c2d43e91c694556094f1245924649c820ceb88 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:21:43 +0000 Subject: [PATCH 09/13] fix: remove version_meta.go file Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- provider/version_meta.go | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 provider/version_meta.go diff --git a/provider/version_meta.go b/provider/version_meta.go deleted file mode 100644 index 05c36fb..0000000 --- a/provider/version_meta.go +++ /dev/null @@ -1,23 +0,0 @@ -package provider - -// VersionMeta provides utilities and constants for managing version metadata in resources. -// Resources and attributes can specify their minimum Coder version requirements -// using the @since: marker in their descriptions. - -// Common version constants for frequently used versions -const ( - // V2_18_0 is the base requirement for terraform-provider-coder v2.0+ - V2_18_0 = "v2.18.0" - - // V2_16_0 introduced the hidden attribute for apps - V2_16_0 = "v2.16.0" - - // V2_21_0 introduced devcontainer support - V2_21_0 = "v2.21.0" - - // V2_24_0 introduced AI task resources - V2_24_0 = "v2.24.0" - - // V2_8_0 introduced workspace preset data source - V2_8_0 = "v2.8.0" -) From 2a429aadd560f0ff784652fc0666ec72d17b5a05 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:33:30 +0000 Subject: [PATCH 10/13] fix: sanitize @since markers from generated documentation - Add cleanVersionMarkers function to remove @since patterns from docs - Apply cleaning in adjustDocFile and processAttributeVersions - @since markers are now only used to extract version info, not displayed - Version notes and inline markers are still added correctly Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> # Conflicts: # docs/resources/script.md --- docs/data-sources/external_auth.md | 43 +----- docs/data-sources/parameter.md | 192 +------------------------- docs/data-sources/provisioner.md | 43 +----- docs/data-sources/workspace.md | 81 +---------- docs/data-sources/workspace_owner.md | 68 +-------- docs/data-sources/workspace_preset.md | 96 +------------ docs/data-sources/workspace_tags.md | 78 +---------- docs/index.md | 78 +---------- docs/resources/agent.md | 149 +------------------- docs/resources/agent_instance.md | 43 +----- docs/resources/ai_task.md | 32 +---- docs/resources/app.md | 88 +----------- docs/resources/devcontainer.md | 32 +---- docs/resources/env.md | 52 +------ docs/resources/metadata.md | 93 +------------ docs/resources/script.md | 103 +------------- scripts/docsgen/main.go | 18 ++- 17 files changed, 34 insertions(+), 1255 deletions(-) diff --git a/docs/data-sources/external_auth.md b/docs/data-sources/external_auth.md index e4089f2..acff9ce 100644 --- a/docs/data-sources/external_auth.md +++ b/docs/data-sources/external_auth.md @@ -1,42 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_external_auth Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.) ---- - -# coder_external_auth (Data Source) - -Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) - -## Example Usage - -```terraform -provider "coder" {} - - -data "coder_external_auth" "github" { - id = "github" -} - -data "coder_external_auth" "azure-identity" { - id = "azure-identiy" - optional = true -} -``` - - -## Schema - -### Required - -- `id` (String) The ID of a configured external auth provider set up in your Coder deployment. - -### Optional - -- `optional` (Boolean) Authenticating with the external auth provider is not required, and can be skipped by users when creating or updating workspaces - -### Read-Only - -- `access_token` (String) The access token returned by the external auth provider. This can be used to pre-authenticate command-line tools. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_external_auth Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.) --- # coder_external_auth (Data Source) Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) ## Example Usage ```terraform provider "coder" {} data "coder_external_auth" "github" { id = "github" } data "coder_external_auth" "azure-identity" { id = "azure-identiy" optional = true } ``` ## Schema ### Required - `id` (String) The ID of a configured external auth provider set up in your Coder deployment. ### Optional - `optional` (Boolean) Authenticating with the external auth provider is not required, and can be skipped by users when creating or updating workspaces ### Read-Only - `access_token` (String) The access token returned by the external auth provider. This can be used to pre-authenticate command-line tools. \ No newline at end of file diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md index ecba392..c62a7bd 100644 --- a/docs/data-sources/parameter.md +++ b/docs/data-sources/parameter.md @@ -1,191 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_parameter Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to configure editable options for workspaces. ---- - -# coder_parameter (Data Source) - -Use this data source to configure editable options for workspaces. - -## Example Usage - -```terraform -provider "coder" {} - -data "coder_parameter" "example" { - name = "Region" - description = "Specify a region to place your workspace." - mutable = false - type = "string" - default = "us-central1-a" - option { - value = "us-central1-a" - name = "US Central" - icon = "/icons/1f1fa-1f1f8.png" - } - option { - value = "asia-southeast1-a" - name = "Singapore" - icon = "/icons/1f1f8-1f1ec.png" - } -} - -data "coder_parameter" "ami" { - name = "Machine Image" - description = <<-EOT - # Provide the machine image - See the [registry](https://container.registry.blah/namespace) for options. - EOT - option { - value = "ami-xxxxxxxx" - name = "Ubuntu" - icon = "/icon/ubuntu.svg" - } -} - -data "coder_parameter" "is_public_instance" { - name = "Is public instance?" - type = "bool" - icon = "/icon/docker.svg" - default = false -} - -data "coder_parameter" "cores" { - name = "CPU Cores" - type = "number" - icon = "/icon/cpu.svg" - default = 3 - order = 10 -} - -data "coder_parameter" "disk_size" { - name = "Disk Size" - type = "number" - default = "5" - order = 8 - validation { - # This can apply to number. - min = 0 - max = 10 - monotonic = "increasing" - } -} - -data "coder_parameter" "cat_lives" { - name = "Cat Lives" - type = "number" - default = "9" - validation { - # This can apply to number. - min = 0 - max = 10 - monotonic = "decreasing" - } -} - -data "coder_parameter" "fairy_tale" { - name = "Fairy Tale" - type = "string" - mutable = true - default = "Hansel and Gretel" - ephemeral = true -} - -data "coder_parameter" "users" { - name = "system_users" - display_name = "System users" - type = "list(string)" - default = jsonencode(["root", "user1", "user2"]) -} - -data "coder_parameter" "home_volume_size" { - name = "Home Volume Size" - description = <<-EOF - How large should your home volume be? - EOF - type = "number" - default = 30 - mutable = true - order = 3 - - option { - name = "30GB" - value = 30 - } - - option { - name = "60GB" - value = 60 - } - - option { - name = "100GB" - value = 100 - } - - validation { - monotonic = "increasing" - } -} -``` - - -## Schema - -### Required - -- `name` (String) The name of the parameter. If this is changed, developers will be re-prompted for a new value. - -### Optional - -- `default` (String) A default value for the parameter. -- `description` (String) Describe what this parameter does. -- `display_name` (String) The displayed name of the parameter as it will appear in the interface. -- `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds. -- `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`. -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. -- `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution! -- `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option)) -- `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order). -- `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. -- `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`. -- `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation)) - -### Read-Only - -- `id` (String) The ID of this resource. -- `optional` (Boolean) Whether this value is optional. -- `value` (String) The output value of the parameter. - - -### Nested Schema for `option` - -Required: - -- `name` (String) The display name of this value in the UI. -- `value` (String) The value of this option set on the parameter if selected. - -Optional: - -- `description` (String) Describe what selecting this value does. -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - - - -### Nested Schema for `validation` - -Optional: - -- `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`. -- `max` (Number) The maximum value of a number parameter. -- `min` (Number) The minimum value of a number parameter. -- `monotonic` (String) Number monotonicity, either increasing or decreasing. -- `regex` (String) A regex for the input parameter to match against. - -Read-Only: - -- `max_disabled` (Boolean) Helper field to check if `max` is present -- `min_disabled` (Boolean) Helper field to check if `min` is present +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_parameter Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to configure editable options for workspaces. --- # coder_parameter (Data Source) Use this data source to configure editable options for workspaces. ## Example Usage ```terraform provider "coder" {} data "coder_parameter" "example" { name = "Region" description = "Specify a region to place your workspace." mutable = false type = "string" default = "us-central1-a" option { value = "us-central1-a" name = "US Central" icon = "/icons/1f1fa-1f1f8.png" } option { value = "asia-southeast1-a" name = "Singapore" icon = "/icons/1f1f8-1f1ec.png" } } data "coder_parameter" "ami" { name = "Machine Image" description = <<-EOT # Provide the machine image See the [registry](https://container.registry.blah/namespace) for options. EOT option { value = "ami-xxxxxxxx" name = "Ubuntu" icon = "/icon/ubuntu.svg" } } data "coder_parameter" "is_public_instance" { name = "Is public instance?" type = "bool" icon = "/icon/docker.svg" default = false } data "coder_parameter" "cores" { name = "CPU Cores" type = "number" icon = "/icon/cpu.svg" default = 3 order = 10 } data "coder_parameter" "disk_size" { name = "Disk Size" type = "number" default = "5" order = 8 validation { # This can apply to number. min = 0 max = 10 monotonic = "increasing" } } data "coder_parameter" "cat_lives" { name = "Cat Lives" type = "number" default = "9" validation { # This can apply to number. min = 0 max = 10 monotonic = "decreasing" } } data "coder_parameter" "fairy_tale" { name = "Fairy Tale" type = "string" mutable = true default = "Hansel and Gretel" ephemeral = true } data "coder_parameter" "users" { name = "system_users" display_name = "System users" type = "list(string)" default = jsonencode(["root", "user1", "user2"]) } data "coder_parameter" "home_volume_size" { name = "Home Volume Size" description = <<-EOF How large should your home volume be? EOF type = "number" default = 30 mutable = true order = 3 option { name = "30GB" value = 30 } option { name = "60GB" value = 60 } option { name = "100GB" value = 100 } validation { monotonic = "increasing" } } ``` ## Schema ### Required - `name` (String) The name of the parameter. If this is changed, developers will be re-prompted for a new value. ### Optional - `default` (String) A default value for the parameter. - `description` (String) Describe what this parameter does. - `display_name` (String) The displayed name of the parameter as it will appear in the interface. - `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds. - `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution! - `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option)) - `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order). - `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. - `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`. - `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation)) ### Read-Only - `id` (String) The ID of this resource. - `optional` (Boolean) Whether this value is optional. - `value` (String) The output value of the parameter. ### Nested Schema for `option` Required: - `name` (String) The display name of this value in the UI. - `value` (String) The value of this option set on the parameter if selected. Optional: - `description` (String) Describe what selecting this value does. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. ### Nested Schema for `validation` Optional: - `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`. - `max` (Number) The maximum value of a number parameter. - `min` (Number) The minimum value of a number parameter. - `monotonic` (String) Number monotonicity, either increasing or decreasing. - `regex` (String) A regex for the input parameter to match against. Read-Only: - `max_disabled` (Boolean) Helper field to check if `max` is present - `min_disabled` (Boolean) Helper field to check if `min` is present \ No newline at end of file diff --git a/docs/data-sources/provisioner.md b/docs/data-sources/provisioner.md index ba930a2..7f584ec 100644 --- a/docs/data-sources/provisioner.md +++ b/docs/data-sources/provisioner.md @@ -1,42 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_provisioner Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to get information about the Coder provisioner. ---- - -# coder_provisioner (Data Source) - -Use this data source to get information about the Coder provisioner. - -## Example Usage - -```terraform -provider "coder" {} - -data "coder_provisioner" "dev" {} - -data "coder_workspace" "dev" {} - -resource "coder_agent" "main" { - arch = data.coder_provisioner.dev.arch - os = data.coder_provisioner.dev.os - dir = "/workspace" - display_apps { - vscode = true - vscode_insiders = false - web_terminal = true - ssh_helper = false - } -} -``` - - -## Schema - -### Read-Only - -- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). -- `id` (String) The ID of this resource. -- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_provisioner Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to get information about the Coder provisioner. --- # coder_provisioner (Data Source) Use this data source to get information about the Coder provisioner. ## Example Usage ```terraform provider "coder" {} data "coder_provisioner" "dev" {} data "coder_workspace" "dev" {} resource "coder_agent" "main" { arch = data.coder_provisioner.dev.arch os = data.coder_provisioner.dev.os dir = "/workspace" display_apps { vscode = true vscode_insiders = false web_terminal = true ssh_helper = false } } ``` ## Schema ### Read-Only - `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). - `id` (String) The ID of this resource. - `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). \ No newline at end of file diff --git a/docs/data-sources/workspace.md b/docs/data-sources/workspace.md index 4dacdfc..d8e9d53 100644 --- a/docs/data-sources/workspace.md +++ b/docs/data-sources/workspace.md @@ -1,80 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_workspace Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to get information for the active workspace build. ---- - -# coder_workspace (Data Source) - -Use this data source to get information for the active workspace build. - -## Example Usage - -```terraform -provider "coder" {} - -provider "docker" {} - -data "coder_workspace" "me" {} - -data "coder_workspace_owner" "me" {} - -resource "coder_agent" "dev" { - arch = "amd64" - os = "linux" - dir = "/workspace" -} - -resource "docker_container" "workspace" { - count = data.coder_workspace.me.start_count - image = docker_image.main.name - # Uses lower() to avoid Docker restriction on container names. - name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" - # Hostname makes the shell more user friendly: coder@my-workspace:~$ - hostname = data.coder_workspace.me.name - # Use the docker gateway if the access URL is 127.0.0.1 - entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")] - env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] - host { - host = "host.docker.internal" - ip = "host-gateway" - } - # Add labels in Docker to keep track of orphan resources. - labels { - label = "coder.owner" - value = data.coder_workspace_owner.me.name - } - labels { - label = "coder.owner_id" - value = data.coder_workspace_owner.me.id - } - labels { - label = "coder.workspace_id" - value = data.coder_workspace.me.id - } - labels { - label = "coder.workspace_name" - value = data.coder_workspace.me.name - } -} -``` - - -## Schema - -### Read-Only - -- `access_port` (Number) The access port of the Coder deployment provisioning this workspace. -- `access_url` (String) The access URL of the Coder deployment provisioning this workspace. -- `id` (String) UUID of the workspace. -- `is_prebuild` (Boolean) Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false. -- `is_prebuild_claim` (Boolean) Indicates whether a prebuilt workspace has just been claimed and this is the first `apply` after that occurrence. -- `name` (String) Name of the workspace. -- `prebuild_count` (Number) A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0. -- `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1. -- `template_id` (String) ID of the workspace's template. -- `template_name` (String) Name of the workspace's template. -- `template_version` (String) Version of the workspace's template. -- `transition` (String) Either `start` or `stop`. Use this to start/stop resources with `count`. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to get information for the active workspace build. --- # coder_workspace (Data Source) Use this data source to get information for the active workspace build. ## Example Usage ```terraform provider "coder" {} provider "docker" {} data "coder_workspace" "me" {} data "coder_workspace_owner" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" dir = "/workspace" } resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count image = docker_image.main.name # Uses lower() to avoid Docker restriction on container names. name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" # Hostname makes the shell more user friendly: coder@my-workspace:~$ hostname = data.coder_workspace.me.name # Use the docker gateway if the access URL is 127.0.0.1 entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")] env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] host { host = "host.docker.internal" ip = "host-gateway" } # Add labels in Docker to keep track of orphan resources. labels { label = "coder.owner" value = data.coder_workspace_owner.me.name } labels { label = "coder.owner_id" value = data.coder_workspace_owner.me.id } labels { label = "coder.workspace_id" value = data.coder_workspace.me.id } labels { label = "coder.workspace_name" value = data.coder_workspace.me.name } } ``` ## Schema ### Read-Only - `access_port` (Number) The access port of the Coder deployment provisioning this workspace. - `access_url` (String) The access URL of the Coder deployment provisioning this workspace. - `id` (String) UUID of the workspace. - `is_prebuild` (Boolean) Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false. - `is_prebuild_claim` (Boolean) Indicates whether a prebuilt workspace has just been claimed and this is the first `apply` after that occurrence. - `name` (String) Name of the workspace. - `prebuild_count` (Number) A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0. - `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1. - `template_id` (String) ID of the workspace's template. - `template_name` (String) Name of the workspace's template. - `template_version` (String) Version of the workspace's template. - `transition` (String) Either `start` or `stop`. Use this to start/stop resources with `count`. \ No newline at end of file diff --git a/docs/data-sources/workspace_owner.md b/docs/data-sources/workspace_owner.md index 2a912e1..92559dd 100644 --- a/docs/data-sources/workspace_owner.md +++ b/docs/data-sources/workspace_owner.md @@ -1,67 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_workspace_owner Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to fetch information about the workspace owner. ---- - -# coder_workspace_owner (Data Source) - -Use this data source to fetch information about the workspace owner. - -## Example Usage - -```terraform -provider "coder" {} - -data "coder_workspace_owner" "me" {} - -resource "coder_agent" "dev" { - arch = "amd64" - os = "linux" - dir = "/workspace" - env = { - OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token, - } -} - -# Add git credentials from coder_workspace_owner -resource "coder_env" "git_author_name" { - agent_id = coder_agent.agent_id - name = "GIT_AUTHOR_NAME" - value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name) -} - -resource "coder_env" "git_author_email" { - agent_id = coder_agent.dev.id - name = "GIT_AUTHOR_EMAIL" - value = data.coder_workspace_owner.me.email - count = data.coder_workspace_owner.me.email != "" ? 1 : 0 -} -``` - - -## Schema - -### Read-Only - -- `email` (String) The email address of the user. -- `full_name` (String) The full name of the user. -- `groups` (List of String) The groups of which the user is a member. -- `id` (String) The UUID of the workspace owner. -- `login_type` (String) The type of login the user has. -- `name` (String) The username of the user. -- `oidc_access_token` (String) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string. -- `rbac_roles` (List of Object) The RBAC roles of which the user is assigned. (see [below for nested schema](#nestedatt--rbac_roles)) -- `session_token` (String) Session token for authenticating with a Coder deployment. It is regenerated every time a workspace is started. -- `ssh_private_key` (String, Sensitive) The user's generated SSH private key. -- `ssh_public_key` (String) The user's generated SSH public key. - - -### Nested Schema for `rbac_roles` - -Read-Only: - -- `name` (String) -- `org_id` (String) +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_owner Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to fetch information about the workspace owner. --- # coder_workspace_owner (Data Source) Use this data source to fetch information about the workspace owner. ## Example Usage ```terraform provider "coder" {} data "coder_workspace_owner" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" dir = "/workspace" env = { OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token, } } # Add git credentials from coder_workspace_owner resource "coder_env" "git_author_name" { agent_id = coder_agent.agent_id name = "GIT_AUTHOR_NAME" value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name) } resource "coder_env" "git_author_email" { agent_id = coder_agent.dev.id name = "GIT_AUTHOR_EMAIL" value = data.coder_workspace_owner.me.email count = data.coder_workspace_owner.me.email != "" ? 1 : 0 } ``` ## Schema ### Read-Only - `email` (String) The email address of the user. - `full_name` (String) The full name of the user. - `groups` (List of String) The groups of which the user is a member. - `id` (String) The UUID of the workspace owner. - `login_type` (String) The type of login the user has. - `name` (String) The username of the user. - `oidc_access_token` (String) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string. - `rbac_roles` (List of Object) The RBAC roles of which the user is assigned. (see [below for nested schema](#nestedatt--rbac_roles)) - `session_token` (String) Session token for authenticating with a Coder deployment. It is regenerated every time a workspace is started. - `ssh_private_key` (String, Sensitive) The user's generated SSH private key. - `ssh_public_key` (String) The user's generated SSH public key. ### Nested Schema for `rbac_roles` Read-Only: - `name` (String) - `org_id` (String) \ No newline at end of file diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md index 6905740..5d0d84c 100644 --- a/docs/data-sources/workspace_preset.md +++ b/docs/data-sources/workspace_preset.md @@ -1,95 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_workspace_preset Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. ---- - -# coder_workspace_preset (Data Source) - -Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. - -## Example Usage - -```terraform -provider "coder" {} - -# presets can be used to predefine common configurations for workspaces -# Parameters are referenced by their name. Each parameter must be defined in the preset. -# Values defined by the preset must pass validation for the parameter. -# See the coder_parameter data source's documentation for examples of how to define -# parameters like the ones used below. -data "coder_workspace_preset" "example" { - name = "example" - parameters = { - (data.coder_parameter.example.name) = "us-central1-a" - (data.coder_parameter.ami.name) = "ami-xxxxxxxx" - } -} - -# Example of a default preset that will be pre-selected for users -data "coder_workspace_preset" "standard" { - name = "Standard" - default = true - parameters = { - (data.coder_parameter.instance_type.name) = "t3.medium" - (data.coder_parameter.region.name) = "us-west-2" - } -} -``` - - -## Schema - -### Required - -- `name` (String) The name of the workspace preset. - -### Optional - -- `default` (Boolean) Whether this preset should be selected by default when creating a workspace. Only one preset per template can be marked as default. -- `parameters` (Map of String) Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version. -- `prebuilds` (Block Set, Max: 1) Configuration for prebuilt workspaces associated with this preset. Coder will maintain a pool of standby workspaces based on this configuration. When a user creates a workspace using this preset, they are assigned a prebuilt workspace instead of waiting for a new one to build. See prebuilt workspace documentation [here](https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces.md) (see [below for nested schema](#nestedblock--prebuilds)) - -### Read-Only - -- `id` (String) The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset. - - -### Nested Schema for `prebuilds` - -Required: - -- `instances` (Number) The number of workspaces to keep in reserve for this preset. - -Optional: - -- `expiration_policy` (Block Set, Max: 1) Configuration block that defines TTL (time-to-live) behavior for prebuilds. Use this to automatically invalidate and delete prebuilds after a certain period, ensuring they stay up-to-date. (see [below for nested schema](#nestedblock--prebuilds--expiration_policy)) -- `scheduling` (Block List, Max: 1) Configuration block that defines scheduling behavior for prebuilds. Use this to automatically adjust the number of prebuild instances based on a schedule. (see [below for nested schema](#nestedblock--prebuilds--scheduling)) - - -### Nested Schema for `prebuilds.expiration_policy` - -Required: - -- `ttl` (Number) Time in seconds after which an unclaimed prebuild is considered expired and eligible for cleanup. - - - -### Nested Schema for `prebuilds.scheduling` - -Required: - -- `schedule` (Block List, Min: 1) One or more schedule blocks that define when to scale the number of prebuild instances. (see [below for nested schema](#nestedblock--prebuilds--scheduling--schedule)) -- `timezone` (String) The timezone to use for the prebuild schedules (e.g., "UTC", "America/New_York"). -Timezone must be a valid timezone in the IANA timezone database. -See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a complete list of valid timezone identifiers and https://www.iana.org/time-zones for the official IANA timezone database. - - -### Nested Schema for `prebuilds.scheduling.schedule` - -Required: - -- `cron` (String) A cron expression that defines when this schedule should be active. The cron expression must be in the format "* HOUR DOM MONTH DAY-OF-WEEK" where HOUR is 0-23, DOM (day-of-month) is 1-31, MONTH is 1-12, and DAY-OF-WEEK is 0-6 (Sunday-Saturday). The minute field must be "*" to ensure the schedule covers entire hours rather than specific minute intervals. -- `instances` (Number) The number of prebuild instances to maintain during this schedule period. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_preset Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. --- # coder_workspace_preset (Data Source) Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. ## Example Usage ```terraform provider "coder" {} # presets can be used to predefine common configurations for workspaces # Parameters are referenced by their name. Each parameter must be defined in the preset. # Values defined by the preset must pass validation for the parameter. # See the coder_parameter data source's documentation for examples of how to define # parameters like the ones used below. data "coder_workspace_preset" "example" { name = "example" parameters = { (data.coder_parameter.example.name) = "us-central1-a" (data.coder_parameter.ami.name) = "ami-xxxxxxxx" } } # Example of a default preset that will be pre-selected for users data "coder_workspace_preset" "standard" { name = "Standard" default = true parameters = { (data.coder_parameter.instance_type.name) = "t3.medium" (data.coder_parameter.region.name) = "us-west-2" } } ``` ## Schema ### Required - `name` (String) The name of the workspace preset. ### Optional - `default` (Boolean) Whether this preset should be selected by default when creating a workspace. Only one preset per template can be marked as default. - `parameters` (Map of String) Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version. - `prebuilds` (Block Set, Max: 1) Configuration for prebuilt workspaces associated with this preset. Coder will maintain a pool of standby workspaces based on this configuration. When a user creates a workspace using this preset, they are assigned a prebuilt workspace instead of waiting for a new one to build. See prebuilt workspace documentation [here](https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces.md) (see [below for nested schema](#nestedblock--prebuilds)) ### Read-Only - `id` (String) The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset. ### Nested Schema for `prebuilds` Required: - `instances` (Number) The number of workspaces to keep in reserve for this preset. Optional: - `expiration_policy` (Block Set, Max: 1) Configuration block that defines TTL (time-to-live) behavior for prebuilds. Use this to automatically invalidate and delete prebuilds after a certain period, ensuring they stay up-to-date. (see [below for nested schema](#nestedblock--prebuilds--expiration_policy)) - `scheduling` (Block List, Max: 1) Configuration block that defines scheduling behavior for prebuilds. Use this to automatically adjust the number of prebuild instances based on a schedule. (see [below for nested schema](#nestedblock--prebuilds--scheduling)) ### Nested Schema for `prebuilds.expiration_policy` Required: - `ttl` (Number) Time in seconds after which an unclaimed prebuild is considered expired and eligible for cleanup. ### Nested Schema for `prebuilds.scheduling` Required: - `schedule` (Block List, Min: 1) One or more schedule blocks that define when to scale the number of prebuild instances. (see [below for nested schema](#nestedblock--prebuilds--scheduling--schedule)) - `timezone` (String) The timezone to use for the prebuild schedules (e.g., "UTC", "America/New_York"). Timezone must be a valid timezone in the IANA timezone database. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a complete list of valid timezone identifiers and https://www.iana.org/time-zones for the official IANA timezone database. ### Nested Schema for `prebuilds.scheduling.schedule` Required: - `cron` (String) A cron expression that defines when this schedule should be active. The cron expression must be in the format "* HOUR DOM MONTH DAY-OF-WEEK" where HOUR is 0-23, DOM (day-of-month) is 1-31, MONTH is 1-12, and DAY-OF-WEEK is 0-6 (Sunday-Saturday). The minute field must be "*" to ensure the schedule covers entire hours rather than specific minute intervals. - `instances` (Number) The number of prebuild instances to maintain during this schedule period. \ No newline at end of file diff --git a/docs/data-sources/workspace_tags.md b/docs/data-sources/workspace_tags.md index 010adfe..34c4a63 100644 --- a/docs/data-sources/workspace_tags.md +++ b/docs/data-sources/workspace_tags.md @@ -1,77 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_workspace_tags Data Source - terraform-provider-coder" -subcategory: "" -description: |- - Use this data source to configure workspace tags to select provisioners. ---- - -# coder_workspace_tags (Data Source) - -Use this data source to configure workspace tags to select provisioners. - -## Example Usage - -```terraform -provider "coder" {} - -data "coder_parameter" "os_selector" { - name = "os_selector" - display_name = "Operating System" - mutable = false - - default = "osx" - - option { - icon = "/icons/linux.png" - name = "Linux" - value = "linux" - } - option { - icon = "/icons/osx.png" - name = "OSX" - value = "osx" - } - option { - icon = "/icons/windows.png" - name = "Windows" - value = "windows" - } -} - -data "coder_parameter" "feature_cache_enabled" { - name = "feature_cache_enabled" - display_name = "Enable cache?" - type = "bool" - - default = false -} - -data "coder_parameter" "feature_debug_enabled" { - name = "feature_debug_enabled" - display_name = "Enable debug?" - type = "bool" - - default = true -} - -data "coder_workspace_tags" "custom_workspace_tags" { - tags = { - "cluster" = "developers" - "os" = data.coder_parameter.os_selector.value - "debug" = "${data.coder_parameter.feature_debug_enabled.value}+12345" - "cache" = data.coder_parameter.feature_cache_enabled.value == "true" ? "nix-with-cache" : "no-cache" - } -} -``` - - -## Schema - -### Optional - -- `tags` (Map of String) Key-value map with workspace tags - -### Read-Only - -- `id` (String) The ID of this resource. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_tags Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to configure workspace tags to select provisioners. --- # coder_workspace_tags (Data Source) Use this data source to configure workspace tags to select provisioners. ## Example Usage ```terraform provider "coder" {} data "coder_parameter" "os_selector" { name = "os_selector" display_name = "Operating System" mutable = false default = "osx" option { icon = "/icons/linux.png" name = "Linux" value = "linux" } option { icon = "/icons/osx.png" name = "OSX" value = "osx" } option { icon = "/icons/windows.png" name = "Windows" value = "windows" } } data "coder_parameter" "feature_cache_enabled" { name = "feature_cache_enabled" display_name = "Enable cache?" type = "bool" default = false } data "coder_parameter" "feature_debug_enabled" { name = "feature_debug_enabled" display_name = "Enable debug?" type = "bool" default = true } data "coder_workspace_tags" "custom_workspace_tags" { tags = { "cluster" = "developers" "os" = data.coder_parameter.os_selector.value "debug" = "${data.coder_parameter.feature_debug_enabled.value}+12345" "cache" = data.coder_parameter.feature_cache_enabled.value == "true" ? "nix-with-cache" : "no-cache" } } ``` ## Schema ### Optional - `tags` (Map of String) Key-value map with workspace tags ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 343ca8b..62eab1e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,77 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "Coder Provider" -subcategory: "Infrastructure" -description: |- - Terraform provider for managing Coder templates, which are the underlying infrastructure for Coder workspaces. ---- - -# Coder Provider - -Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). - --> Requires Coder [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. - -!> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. - -## Version Compatibility - -This provider automatically documents version requirements for individual resources and features. - -~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. - -## Example - -```terraform -terraform { - required_providers { - coder = { - source = "coder/coder" - } - } -} - -provider "google" { - region = "us-central1" -} - -data "coder_workspace" "me" {} - -resource "coder_agent" "dev" { - arch = "amd64" - os = "linux" - auth = "google-instance-identity" -} - -data "google_compute_default_service_account" "default" {} - -resource "google_compute_instance" "dev" { - zone = "us-central1-a" - count = data.coder_workspace.me.start_count - name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" - machine_type = "e2-medium" - network_interface { - network = "default" - access_config { - // Ephemeral public IP - } - } - boot_disk { - initialize_params { - image = "debian-cloud/debian-9" - } - } - service_account { - email = data.google_compute_default_service_account.default.email - scopes = ["cloud-platform"] - } - metadata_startup_script = coder_agent.dev.init_script -} -``` - - -## Schema - -### Optional - -- `url` (String) The URL to access Coder. \ No newline at end of file +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "Coder Provider" subcategory: "Infrastructure" description: |- Terraform provider for managing Coder templates, which are the underlying infrastructure for Coder workspaces. --- # Coder Provider Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). -> Requires Coder [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. ## Version Compatibility This provider automatically documents version requirements for individual resources and features. ~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. ## Example ```terraform terraform { required_providers { coder = { source = "coder/coder" } } } provider "google" { region = "us-central1" } data "coder_workspace" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" auth = "google-instance-identity" } data "google_compute_default_service_account" "default" {} resource "google_compute_instance" "dev" { zone = "us-central1-a" count = data.coder_workspace.me.start_count name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" machine_type = "e2-medium" network_interface { network = "default" access_config { // Ephemeral public IP } } boot_disk { initialize_params { image = "debian-cloud/debian-9" } } service_account { email = data.google_compute_default_service_account.default.email scopes = ["cloud-platform"] } metadata_startup_script = coder_agent.dev.init_script } ``` ## Schema ### Optional - `url` (String) The URL to access Coder. \ No newline at end of file diff --git a/docs/resources/agent.md b/docs/resources/agent.md index 87ab423..b635f0a 100644 --- a/docs/resources/agent.md +++ b/docs/resources/agent.md @@ -1,148 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_agent Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to associate an agent. ---- - -# coder_agent (Resource) - -Use this resource to associate an agent. - -## Example Usage - -```terraform -data "coder_workspace" "me" { -} - -resource "coder_agent" "dev" { - os = "linux" - arch = "amd64" - dir = "/workspace" - api_key_scope = "all" - display_apps { - vscode = true - vscode_insiders = false - web_terminal = true - ssh_helper = false - } - - metadata { - display_name = "CPU Usage" - key = "cpu_usage" - script = "coder stat cpu" - interval = 10 - timeout = 1 - order = 2 - } - metadata { - display_name = "RAM Usage" - key = "ram_usage" - script = "coder stat mem" - interval = 10 - timeout = 1 - order = 1 - } - - order = 1 -} - -resource "kubernetes_pod" "dev" { - count = data.coder_workspace.me.start_count - spec { - container { - command = ["sh", "-c", coder_agent.dev.init_script] - env { - name = "CODER_AGENT_TOKEN" - value = coder_agent.dev.token - } - } - } -} -``` - - -## Schema - -### Required - -- `arch` (String) The architecture the agent will run on. Must be one of: `"amd64"`, `"armv7"`, `"arm64"`. -- `os` (String) The operating system the agent will run on. Must be one of: `"linux"`, `"darwin"`, or `"windows"`. - -### Optional - -- `api_key_scope` (String) Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes) -- `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`. -- `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out. -- `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`. -- `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps)) -- `env` (Map of String) A mapping of environment variables to set inside the workspace. -- `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata)) -- `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be `"/etc/motd"`. -- `order` (Number) The order determines the position of agents in the UI presentation. The lowest order is shown first and agents with equal order are sorted by name (ascending order). -- `resources_monitoring` (Block Set, Max: 1) The resources monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring)) -- `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a `coder_script` resource with `run_on_stop` set to `true`. -- `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a `coder_script` resource with `run_on_start` set to `true`. -- `startup_script_behavior` (String) This option sets the behavior of the `startup_script`. When set to `"blocking"`, the `startup_script` must exit before the workspace is ready. When set to `"non-blocking"`, the `startup_script` may run in the background and the workspace will be ready immediately. Default is `"non-blocking"`, although `"blocking"` is recommended. This option is an alias for defining a `coder_script` resource with `start_blocks_login` set to `true` (blocking). -- `troubleshooting_url` (String) A URL to a document with instructions for troubleshooting problems with the agent. - -### Read-Only - -- `id` (String) The ID of this resource. -- `init_script` (String) Run this script on startup of an instance to initialize the agent. -- `token` (String, Sensitive) Set the environment variable `CODER_AGENT_TOKEN` with this token to authenticate an agent. - - -### Nested Schema for `display_apps` - -Optional: - -- `port_forwarding_helper` (Boolean) Display the port-forwarding helper button in the agent bar. -- `ssh_helper` (Boolean) Display the SSH helper button in the agent bar. -- `vscode` (Boolean) Display the VSCode Desktop app in the agent bar. -- `vscode_insiders` (Boolean) Display the VSCode Insiders app in the agent bar. -- `web_terminal` (Boolean) Display the web terminal app in the agent bar. - - - -### Nested Schema for `metadata` - -Required: - -- `interval` (Number) The interval in seconds at which to refresh this metadata item. -- `key` (String) The key of this metadata item. -- `script` (String) The script that retrieves the value of this metadata item. - -Optional: - -- `display_name` (String) The user-facing name of this value. -- `order` (Number) The order determines the position of agent metadata in the UI presentation. The lowest order is shown first and metadata with equal order are sorted by key (ascending order). -- `timeout` (Number) The maximum time the command is allowed to run in seconds. - - - -### Nested Schema for `resources_monitoring` - -Optional: - -- `memory` (Block Set, Max: 1) The memory monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--memory)) -- `volume` (Block Set) The volumes monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--volume)) - - -### Nested Schema for `resources_monitoring.memory` - -Required: - -- `enabled` (Boolean) Enable memory monitoring for this agent. -- `threshold` (Number) The memory usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. - - - -### Nested Schema for `resources_monitoring.volume` - -Required: - -- `enabled` (Boolean) Enable volume monitoring for this agent. -- `path` (String) The path of the volume to monitor. -- `threshold` (Number) The volume usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_agent Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to associate an agent. --- # coder_agent (Resource) Use this resource to associate an agent. ## Example Usage ```terraform data "coder_workspace" "me" { } resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" api_key_scope = "all" display_apps { vscode = true vscode_insiders = false web_terminal = true ssh_helper = false } metadata { display_name = "CPU Usage" key = "cpu_usage" script = "coder stat cpu" interval = 10 timeout = 1 order = 2 } metadata { display_name = "RAM Usage" key = "ram_usage" script = "coder stat mem" interval = 10 timeout = 1 order = 1 } order = 1 } resource "kubernetes_pod" "dev" { count = data.coder_workspace.me.start_count spec { container { command = ["sh", "-c", coder_agent.dev.init_script] env { name = "CODER_AGENT_TOKEN" value = coder_agent.dev.token } } } } ``` ## Schema ### Required - `arch` (String) The architecture the agent will run on. Must be one of: `"amd64"`, `"armv7"`, `"arm64"`. - `os` (String) The operating system the agent will run on. Must be one of: `"linux"`, `"darwin"`, or `"windows"`. ### Optional - `api_key_scope` (String) Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes) - `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`. - `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out. - `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`. - `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps)) - `env` (Map of String) A mapping of environment variables to set inside the workspace. - `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata)) - `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be `"/etc/motd"`. - `order` (Number) The order determines the position of agents in the UI presentation. The lowest order is shown first and agents with equal order are sorted by name (ascending order). - `resources_monitoring` (Block Set, Max: 1) The resources monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring)) - `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a `coder_script` resource with `run_on_stop` set to `true`. - `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a `coder_script` resource with `run_on_start` set to `true`. - `startup_script_behavior` (String) This option sets the behavior of the `startup_script`. When set to `"blocking"`, the `startup_script` must exit before the workspace is ready. When set to `"non-blocking"`, the `startup_script` may run in the background and the workspace will be ready immediately. Default is `"non-blocking"`, although `"blocking"` is recommended. This option is an alias for defining a `coder_script` resource with `start_blocks_login` set to `true` (blocking). - `troubleshooting_url` (String) A URL to a document with instructions for troubleshooting problems with the agent. ### Read-Only - `id` (String) The ID of this resource. - `init_script` (String) Run this script on startup of an instance to initialize the agent. - `token` (String, Sensitive) Set the environment variable `CODER_AGENT_TOKEN` with this token to authenticate an agent. ### Nested Schema for `display_apps` Optional: - `port_forwarding_helper` (Boolean) Display the port-forwarding helper button in the agent bar. - `ssh_helper` (Boolean) Display the SSH helper button in the agent bar. - `vscode` (Boolean) Display the VSCode Desktop app in the agent bar. - `vscode_insiders` (Boolean) Display the VSCode Insiders app in the agent bar. - `web_terminal` (Boolean) Display the web terminal app in the agent bar. ### Nested Schema for `metadata` Required: - `interval` (Number) The interval in seconds at which to refresh this metadata item. - `key` (String) The key of this metadata item. - `script` (String) The script that retrieves the value of this metadata item. Optional: - `display_name` (String) The user-facing name of this value. - `order` (Number) The order determines the position of agent metadata in the UI presentation. The lowest order is shown first and metadata with equal order are sorted by key (ascending order). - `timeout` (Number) The maximum time the command is allowed to run in seconds. ### Nested Schema for `resources_monitoring` Optional: - `memory` (Block Set, Max: 1) The memory monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--memory)) - `volume` (Block Set) The volumes monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--volume)) ### Nested Schema for `resources_monitoring.memory` Required: - `enabled` (Boolean) Enable memory monitoring for this agent. - `threshold` (Number) The memory usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. ### Nested Schema for `resources_monitoring.volume` Required: - `enabled` (Boolean) Enable volume monitoring for this agent. - `path` (String) The path of the volume to monitor. - `threshold` (Number) The volume usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. \ No newline at end of file diff --git a/docs/resources/agent_instance.md b/docs/resources/agent_instance.md index ec855b1..ffcdc66 100644 --- a/docs/resources/agent_instance.md +++ b/docs/resources/agent_instance.md @@ -1,42 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_agent_instance Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for "google_compute_instance", "aws_instance", "azurerm_linux_virtual_machine", and "azurerm_windows_virtual_machine" resources. ---- - -# coder_agent_instance (Resource) - -Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. - -## Example Usage - -```terraform -resource "coder_agent" "dev" { - os = "linux" - arch = "amd64" - auth = "google-instance-identity" -} - -resource "google_compute_instance" "dev" { - zone = "us-central1-a" -} - -resource "coder_agent_instance" "dev" { - agent_id = coder_agent.dev.id - instance_id = google_compute_instance.dev.instance_id -} -``` - - -## Schema - -### Required - -- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. -- `instance_id` (String) The instance identifier of a provisioned resource. - -### Read-Only - -- `id` (String) The ID of this resource. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_agent_instance Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for "google_compute_instance", "aws_instance", "azurerm_linux_virtual_machine", and "azurerm_windows_virtual_machine" resources. --- # coder_agent_instance (Resource) Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. ## Example Usage ```terraform resource "coder_agent" "dev" { os = "linux" arch = "amd64" auth = "google-instance-identity" } resource "google_compute_instance" "dev" { zone = "us-central1-a" } resource "coder_agent_instance" "dev" { agent_id = coder_agent.dev.id instance_id = google_compute_instance.dev.instance_id } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `instance_id` (String) The instance identifier of a provisioned resource. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index 1922ef5..7a8b1a5 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -1,31 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_ai_task Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to define Coder tasks. ---- - -# coder_ai_task (Resource) - -Use this resource to define Coder tasks. - - - - -## Schema - -### Required - -- `sidebar_app` (Block Set, Min: 1, Max: 1) The coder_app to display in the sidebar. Usually a chat interface with the AI agent running in the workspace, like https://github.com/coder/agentapi. (see [below for nested schema](#nestedblock--sidebar_app)) - -### Read-Only - -- `id` (String) A unique identifier for this resource. - - -### Nested Schema for `sidebar_app` - -Required: - -- `id` (String) A reference to an existing `coder_app` resource in your template. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to define Coder tasks. --- # coder_ai_task (Resource) Use this resource to define Coder tasks. ## Schema ### Required - `sidebar_app` (Block Set, Min: 1, Max: 1) The coder_app to display in the sidebar. Usually a chat interface with the AI agent running in the workspace, like https://github.com/coder/agentapi. (see [below for nested schema](#nestedblock--sidebar_app)) ### Read-Only - `id` (String) A unique identifier for this resource. ### Nested Schema for `sidebar_app` Required: - `id` (String) A reference to an existing `coder_app` resource in your template. \ No newline at end of file diff --git a/docs/resources/app.md b/docs/resources/app.md index cad082b..47aebf9 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -1,87 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_app Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to define shortcuts to access applications in a workspace. ---- - -# coder_app (Resource) - -Use this resource to define shortcuts to access applications in a workspace. - -## Example Usage - -```terraform -data "coder_workspace" "me" {} - -resource "coder_agent" "dev" { - os = "linux" - arch = "amd64" - dir = "/workspace" - startup_script = < -## Schema - -### Required - -- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. -- `slug` (String) A hostname-friendly name for the app. This is used in URLs to access the app. May contain alphanumerics and hyphens. Cannot start/end with a hyphen or contain two consecutive hyphens. - -### Optional - -- `command` (String) A command to run in a terminal opening this app. In the web, this will open in a new tab. In the CLI, this will SSH and execute the command. Either `command` or `url` may be specified, but not both. -- `display_name` (String) A display name to identify the app. Defaults to the slug. -- `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. -- `group` (String) The name of a group that this app belongs to. -- `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) -- `hidden` (Boolean) Determines if the app is visible in the UI. -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. -- `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. -- `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). -- `share` (String) Determines the level which the application is shared at. Valid levels are `"owner"` (default), `"authenticated"` and `"public"`. Level `"owner"` disables sharing on the app, so only the workspace owner can access it. Level `"authenticated"` shares the app with all authenticated users. Level `"public"` shares it with any user, including unauthenticated users. Permitted application sharing levels can be configured site-wide via a flag on `coder server` (Enterprise only). -- `subdomain` (Boolean) Determines whether the app will be accessed via it's own subdomain or whether it will be accessed via a path on Coder. If wildcards have not been setup by the administrator then apps with `subdomain` set to `true` will not be accessible. Defaults to `false`. -- `url` (String) An external url if `external=true` or a URL to be proxied to from inside the workspace. This should be of the form `http://localhost:PORT[/SUBPATH]`. Either `command` or `url` may be specified, but not both. - -### Read-Only - -- `id` (String) The ID of this resource. - - -### Nested Schema for `healthcheck` - -Required: - -- `interval` (Number) Duration in seconds to wait between healthcheck requests. -- `threshold` (Number) Number of consecutive heathcheck failures before returning an unhealthy status. -- `url` (String) HTTP address used determine the application readiness. A successful health check is a HTTP response code less than 500 returned before `healthcheck.interval` seconds. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_app Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to define shortcuts to access applications in a workspace. --- # coder_app (Resource) Use this resource to define shortcuts to access applications in a workspace. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" startup_script = < ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `slug` (String) A hostname-friendly name for the app. This is used in URLs to access the app. May contain alphanumerics and hyphens. Cannot start/end with a hyphen or contain two consecutive hyphens. ### Optional - `command` (String) A command to run in a terminal opening this app. In the web, this will open in a new tab. In the CLI, this will SSH and execute the command. Either `command` or `url` may be specified, but not both. - `display_name` (String) A display name to identify the app. Defaults to the slug. - `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. - `group` (String) The name of a group that this app belongs to. - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) - `hidden` (Boolean) Determines if the app is visible in the UI. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). - `share` (String) Determines the level which the application is shared at. Valid levels are `"owner"` (default), `"authenticated"` and `"public"`. Level `"owner"` disables sharing on the app, so only the workspace owner can access it. Level `"authenticated"` shares the app with all authenticated users. Level `"public"` shares it with any user, including unauthenticated users. Permitted application sharing levels can be configured site-wide via a flag on `coder server` (Enterprise only). - `subdomain` (Boolean) Determines whether the app will be accessed via it's own subdomain or whether it will be accessed via a path on Coder. If wildcards have not been setup by the administrator then apps with `subdomain` set to `true` will not be accessible. Defaults to `false`. - `url` (String) An external url if `external=true` or a URL to be proxied to from inside the workspace. This should be of the form `http://localhost:PORT[/SUBPATH]`. Either `command` or `url` may be specified, but not both. ### Read-Only - `id` (String) The ID of this resource. ### Nested Schema for `healthcheck` Required: - `interval` (Number) Duration in seconds to wait between healthcheck requests. - `threshold` (Number) Number of consecutive heathcheck failures before returning an unhealthy status. - `url` (String) HTTP address used determine the application readiness. A successful health check is a HTTP response code less than 500 returned before `healthcheck.interval` seconds. \ No newline at end of file diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index f0b4dfc..dbbd4c7 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -1,31 +1,3 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_devcontainer Resource - terraform-provider-coder" -subcategory: "" -description: |- - Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0 ---- +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_devcontainer Resource - terraform-provider-coder" subcategory: "" description: |- Define a Dev Container the agent should know of and attempt to autostart. --- # coder_devcontainer (Resource) Define a Dev Container the agent should know of and attempt to autostart. ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `workspace_folder` (String) The workspace folder to for the Dev Container. ### Optional - `config_path` (String) The path to the Dev Container configuration file (devcontainer.json). ### Read-Only - `id` (String) The ID of this resource. -# coder_devcontainer (Resource) - -Define a Dev Container the agent should know of and attempt to autostart. @since:v2.21.0 - -~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. - - - - -## Schema - -### Required - -- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. -- `workspace_folder` (String) The workspace folder to for the Dev Container. - -### Optional - -- `config_path` (String) The path to the Dev Container configuration file (devcontainer.json). - -### Read-Only - -- `id` (String) The ID of this resource. +~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. \ No newline at end of file diff --git a/docs/resources/env.md b/docs/resources/env.md index 3a5a7f3..b6947d0 100644 --- a/docs/resources/env.md +++ b/docs/resources/env.md @@ -1,51 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_env Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the coder_agent resource. ---- - -# coder_env (Resource) - -Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. - -## Example Usage - -```terraform -data "coder_workspace" "me" {} - -resource "coder_agent" "dev" { - os = "linux" - arch = "amd64" - dir = "/workspace" -} - -resource "coder_env" "welcome_message" { - agent_id = coder_agent.dev.id - name = "WELCOME_MESSAGE" - value = "Welcome to your Coder workspace!" -} - -resource "coder_env" "internal_api_url" { - agent_id = coder_agent.dev.id - name = "INTERNAL_API_URL" - value = "https://api.internal.company.com/v1" -} -``` - - -## Schema - -### Required - -- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. -- `name` (String) The name of the environment variable. - -### Optional - -- `value` (String) The value of the environment variable. - -### Read-Only - -- `id` (String) The ID of this resource. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_env Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the coder_agent resource. --- # coder_env (Resource) Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" } resource "coder_env" "welcome_message" { agent_id = coder_agent.dev.id name = "WELCOME_MESSAGE" value = "Welcome to your Coder workspace!" } resource "coder_env" "internal_api_url" { agent_id = coder_agent.dev.id name = "INTERNAL_API_URL" value = "https://api.internal.company.com/v1" } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `name` (String) The name of the environment variable. ### Optional - `value` (String) The value of the environment variable. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md index d8329ea..26daf42 100644 --- a/docs/resources/metadata.md +++ b/docs/resources/metadata.md @@ -1,92 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_metadata Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. - Alternatively, to attach metadata to the agent, use a metadata block within a coder_agent resource. ---- - -# coder_metadata (Resource) - -Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. - -Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. - -## Example Usage - -```terraform -data "coder_workspace" "me" { -} - -resource "kubernetes_pod" "dev" { - count = data.coder_workspace.me.start_count - metadata { - name = "k8s_example" - namespace = "example" - } - spec { - # Draw the rest of the pod! - } -} - -resource "tls_private_key" "example_key_pair" { - algorithm = "ECDSA" - ecdsa_curve = "P256" -} - -resource "coder_metadata" "pod_info" { - count = data.coder_workspace.me.start_count - resource_id = kubernetes_pod.dev[0].id - # (Enterprise-only) this resource consumes 200 quota units - daily_cost = 200 - item { - key = "description" - value = "This description will show up in the Coder dashboard." - } - item { - key = "pod_uid" - value = kubernetes_pod.dev[0].uid - } - item { - key = "public_key" - value = tls_private_key.example_key_pair.public_key_openssh - # The value of this item will be hidden from view by default - sensitive = true - } -} -``` - - -## Schema - -### Required - -- `resource_id` (String) The `id` property of another resource that metadata should be attached to. - -### Optional - -- `daily_cost` (Number) (Enterprise) The cost of this resource every 24 hours. Use the smallest denomination of your preferred currency. For example, if you work in USD, use cents. -- `hide` (Boolean) Hide the resource from the UI. -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. -- `item` (Block List) Each `item` block defines a single metadata item consisting of a key/value pair. (see [below for nested schema](#nestedblock--item)) - -### Read-Only - -- `id` (String) The ID of this resource. - - -### Nested Schema for `item` - -Required: - -- `key` (String) The key of this metadata item. - -Optional: - -- `sensitive` (Boolean) Set to `true` to for items such as API keys whose values should be hidden from view by default. Note that this does not prevent metadata from being retrieved using the API, so it is not suitable for secrets that should not be exposed to workspace users. -- `value` (String) The value of this metadata item. Supports basic Markdown, including hyperlinks. - -Read-Only: - -- `is_null` (Boolean) +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_metadata Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. Alternatively, to attach metadata to the agent, use a metadata block within a coder_agent resource. --- # coder_metadata (Resource) Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. ## Example Usage ```terraform data "coder_workspace" "me" { } resource "kubernetes_pod" "dev" { count = data.coder_workspace.me.start_count metadata { name = "k8s_example" namespace = "example" } spec { # Draw the rest of the pod! } } resource "tls_private_key" "example_key_pair" { algorithm = "ECDSA" ecdsa_curve = "P256" } resource "coder_metadata" "pod_info" { count = data.coder_workspace.me.start_count resource_id = kubernetes_pod.dev[0].id # (Enterprise-only) this resource consumes 200 quota units daily_cost = 200 item { key = "description" value = "This description will show up in the Coder dashboard." } item { key = "pod_uid" value = kubernetes_pod.dev[0].uid } item { key = "public_key" value = tls_private_key.example_key_pair.public_key_openssh # The value of this item will be hidden from view by default sensitive = true } } ``` ## Schema ### Required - `resource_id` (String) The `id` property of another resource that metadata should be attached to. ### Optional - `daily_cost` (Number) (Enterprise) The cost of this resource every 24 hours. Use the smallest denomination of your preferred currency. For example, if you work in USD, use cents. - `hide` (Boolean) Hide the resource from the UI. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `item` (Block List) Each `item` block defines a single metadata item consisting of a key/value pair. (see [below for nested schema](#nestedblock--item)) ### Read-Only - `id` (String) The ID of this resource. ### Nested Schema for `item` Required: - `key` (String) The key of this metadata item. Optional: - `sensitive` (Boolean) Set to `true` to for items such as API keys whose values should be hidden from view by default. Note that this does not prevent metadata from being retrieved using the API, so it is not suitable for secrets that should not be exposed to workspace users. - `value` (String) The value of this metadata item. Supports basic Markdown, including hyperlinks. Read-Only: - `is_null` (Boolean) \ No newline at end of file diff --git a/docs/resources/script.md b/docs/resources/script.md index 21bfaec..ef77d5b 100644 --- a/docs/resources/script.md +++ b/docs/resources/script.md @@ -1,102 +1 @@ ---- -# generated by https://github.com/hashicorp/terraform-plugin-docs -page_title: "coder_script Resource - terraform-provider-coder" -subcategory: "" -description: |- - Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. ---- - -# coder_script (Resource) - -Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. - -## Example Usage - -```terraform -data "coder_workspace" "me" {} - -resource "coder_agent" "dev" { - os = "linux" - arch = "amd64" - dir = "/workspace" -} - -resource "coder_script" "dotfiles" { - agent_id = coder_agent.dev.id - display_name = "Dotfiles" - icon = "/icon/dotfiles.svg" - run_on_start = true - script = templatefile("~/get_dotfiles.sh", { - DOTFILES_URI : var.dotfiles_uri, - DOTFILES_USER : var.dotfiles_user - }) -} - -resource "coder_script" "code-server" { - agent_id = coder_agent.dev.id - display_name = "code-server" - icon = "/icon/code.svg" - run_on_start = true - start_blocks_login = true - script = templatefile("./install-code-server.sh", { - LOG_PATH : "/tmp/code-server.log" - }) -} - -resource "coder_script" "nightly_update" { - agent_id = coder_agent.dev.id - display_name = "Nightly update" - icon = "/icon/database.svg" - cron = "0 0 22 * * *" # Run at 22:00 (10 PM) every day - script = </tmp/pid.log 2>&1 & - EOF -} -``` - - -## Schema - -### Required - -- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. -- `display_name` (String) The display name of the script to display logs in the dashboard. -- `script` (String) The content of the script that will be run. - -### Optional - -- `cron` (String) The cron schedule to run the script on. This uses a 6-field cron expression format: `seconds minutes hours day-of-month month day-of-week`. Note that this differs from the standard Unix 5-field format by including seconds as the first field. Examples: `"0 0 22 * * *"` (daily at 10 PM), `"0 */5 * * * *"` (every 5 minutes), `"30 0 9 * * 1-5"` (weekdays at 9:30 AM). -- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. -- `log_path` (String) The path of a file to write the logs to. If relative, it will be appended to tmp. -- `run_on_start` (Boolean) This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready. -- `run_on_stop` (Boolean) This option defines whether or not the script should run when the agent stops. The script should exit when it is done to signal that the workspace can be stopped. -- `start_blocks_login` (Boolean) This option determines whether users can log in immediately or must wait for the workspace to finish running this script upon startup. If not enabled, users may encounter an incomplete workspace when logging in. This option only sets the default, the user can still manually override the behavior. -- `timeout` (Number) Time in seconds that the script is allowed to run. If the script does not complete within this time, the script is terminated and the agent lifecycle status is marked as timed out. A value of zero (default) means no timeout. - -### Read-Only - -- `id` (String) The ID of this resource. +--- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_script Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. --- # coder_script (Resource) Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" } resource "coder_script" "dotfiles" { agent_id = coder_agent.dev.agent_id display_name = "Dotfiles" icon = "/icon/dotfiles.svg" run_on_start = true script = templatefile("~/get_dotfiles.sh", { DOTFILES_URI : var.dotfiles_uri, DOTFILES_USER : var.dotfiles_user }) } resource "coder_script" "code-server" { agent_id = coder_agent.dev.agent_id display_name = "code-server" icon = "/icon/code.svg" run_on_start = true start_blocks_login = true script = templatefile("./install-code-server.sh", { LOG_PATH : "/tmp/code-server.log" }) } resource "coder_script" "nightly_sleep_reminder" { agent_id = coder_agent.dev.agent_id display_name = "Nightly update" icon = "/icon/database.svg" cron = "0 22 * * *" script = </tmp/pid.log 2>&1 & EOF } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `display_name` (String) The display name of the script to display logs in the dashboard. - `script` (String) The content of the script that will be run. ### Optional - `cron` (String) The cron schedule to run the script on. This is a cron expression. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `log_path` (String) The path of a file to write the logs to. If relative, it will be appended to tmp. - `run_on_start` (Boolean) This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready. - `run_on_stop` (Boolean) This option defines whether or not the script should run when the agent stops. The script should exit when it is done to signal that the workspace can be stopped. - `start_blocks_login` (Boolean) This option determines whether users can log in immediately or must wait for the workspace to finish running this script upon startup. If not enabled, users may encounter an incomplete workspace when logging in. This option only sets the default, the user can still manually override the behavior. - `timeout` (Number) Time in seconds that the script is allowed to run. If the script does not complete within this time, the script is terminated and the agent lifecycle status is marked as timed out. A value of zero (default) means no timeout. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index c4c5f69..cc0456a 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -80,6 +80,9 @@ func adjustDocFile(docPath string, schemas map[string]*schema.Schema) error { } result := writeDeprecationMessage(doc, schemas) + + // Clean @since markers from the final documentation + result = cleanVersionMarkers(result) err = os.WriteFile(docPath, result, 0644) if err != nil { @@ -103,6 +106,17 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by }) } +// cleanVersionMarkers removes @since markers from the documentation +func cleanVersionMarkers(doc []byte) []byte { + // Remove @since:vX.Y.Z patterns from the documentation + result := reVersionPattern.ReplaceAll(doc, []byte("")) + // Clean up any extra spaces that might be left + result = regexp.MustCompile(`\s+`).ReplaceAll(result, []byte(" ")) + // Clean up trailing spaces at end of lines + result = regexp.MustCompile(` +\n`).ReplaceAll(result, []byte("\n")) + return result +} + func processVersionInformation(p *schema.Provider) error { // Process data sources for dataSourceName, dataSource := range p.DataSourcesMap { @@ -274,7 +288,9 @@ func processAttributeVersions(docPath string, schemas map[string]*schema.Schema) } if modified { - err = os.WriteFile(docPath, []byte(docStr), 0644) + // Clean any remaining @since markers from the final document + cleanedDoc := cleanVersionMarkers([]byte(docStr)) + err = os.WriteFile(docPath, cleanedDoc, 0644) if err != nil { return xerrors.Errorf("can't write modified doc file: %w", err) } From e073cc7cb11f424d8549e8ee8cf25e21031e0587 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:32:14 +0000 Subject: [PATCH 11/13] fix: preserve documentation formatting when cleaning @since markers - Fix cleanVersionMarkers to only remove double spaces, not all whitespace - Preserve newlines and YAML frontmatter formatting - Documentation now renders properly formatted Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/data-sources/external_auth.md | 43 +++++- docs/data-sources/parameter.md | 192 +++++++++++++++++++++++++- docs/data-sources/provisioner.md | 43 +++++- docs/data-sources/workspace.md | 81 ++++++++++- docs/data-sources/workspace_owner.md | 68 ++++++++- docs/data-sources/workspace_preset.md | 96 ++++++++++++- docs/data-sources/workspace_tags.md | 78 ++++++++++- docs/index.md | 78 ++++++++++- docs/resources/agent.md | 149 +++++++++++++++++++- docs/resources/agent_instance.md | 43 +++++- docs/resources/ai_task.md | 32 ++++- docs/resources/app.md | 88 +++++++++++- docs/resources/devcontainer.md | 32 ++++- docs/resources/env.md | 52 ++++++- docs/resources/metadata.md | 93 ++++++++++++- docs/resources/script.md | 92 +++++++++++- scripts/docsgen/main.go | 8 +- 17 files changed, 1248 insertions(+), 20 deletions(-) diff --git a/docs/data-sources/external_auth.md b/docs/data-sources/external_auth.md index acff9ce..83ed9ef 100644 --- a/docs/data-sources/external_auth.md +++ b/docs/data-sources/external_auth.md @@ -1 +1,42 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_external_auth Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.) --- # coder_external_auth (Data Source) Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) ## Example Usage ```terraform provider "coder" {} data "coder_external_auth" "github" { id = "github" } data "coder_external_auth" "azure-identity" { id = "azure-identiy" optional = true } ``` ## Schema ### Required - `id` (String) The ID of a configured external auth provider set up in your Coder deployment. ### Optional - `optional` (Boolean) Authenticating with the external auth provider is not required, and can be skipped by users when creating or updating workspaces ### Read-Only - `access_token` (String) The access token returned by the external auth provider. This can be used to pre-authenticate command-line tools. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_external_auth Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.) +--- + +# coder_external_auth (Data Source) + +Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.) + +## Example Usage + +```terraform +provider "coder" {} + + +data "coder_external_auth" "github" { + id = "github" +} + +data "coder_external_auth" "azure-identity" { + id = "azure-identiy" + optional = true +} +``` + + +## Schema + +### Required + +- `id` (String) The ID of a configured external auth provider set up in your Coder deployment. + +### Optional + +- `optional` (Boolean) Authenticating with the external auth provider is not required, and can be skipped by users when creating or updating workspaces + +### Read-Only + +- `access_token` (String) The access token returned by the external auth provider. This can be used to pre-authenticate command-line tools. diff --git a/docs/data-sources/parameter.md b/docs/data-sources/parameter.md index c62a7bd..656f674 100644 --- a/docs/data-sources/parameter.md +++ b/docs/data-sources/parameter.md @@ -1 +1,191 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_parameter Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to configure editable options for workspaces. --- # coder_parameter (Data Source) Use this data source to configure editable options for workspaces. ## Example Usage ```terraform provider "coder" {} data "coder_parameter" "example" { name = "Region" description = "Specify a region to place your workspace." mutable = false type = "string" default = "us-central1-a" option { value = "us-central1-a" name = "US Central" icon = "/icons/1f1fa-1f1f8.png" } option { value = "asia-southeast1-a" name = "Singapore" icon = "/icons/1f1f8-1f1ec.png" } } data "coder_parameter" "ami" { name = "Machine Image" description = <<-EOT # Provide the machine image See the [registry](https://container.registry.blah/namespace) for options. EOT option { value = "ami-xxxxxxxx" name = "Ubuntu" icon = "/icon/ubuntu.svg" } } data "coder_parameter" "is_public_instance" { name = "Is public instance?" type = "bool" icon = "/icon/docker.svg" default = false } data "coder_parameter" "cores" { name = "CPU Cores" type = "number" icon = "/icon/cpu.svg" default = 3 order = 10 } data "coder_parameter" "disk_size" { name = "Disk Size" type = "number" default = "5" order = 8 validation { # This can apply to number. min = 0 max = 10 monotonic = "increasing" } } data "coder_parameter" "cat_lives" { name = "Cat Lives" type = "number" default = "9" validation { # This can apply to number. min = 0 max = 10 monotonic = "decreasing" } } data "coder_parameter" "fairy_tale" { name = "Fairy Tale" type = "string" mutable = true default = "Hansel and Gretel" ephemeral = true } data "coder_parameter" "users" { name = "system_users" display_name = "System users" type = "list(string)" default = jsonencode(["root", "user1", "user2"]) } data "coder_parameter" "home_volume_size" { name = "Home Volume Size" description = <<-EOF How large should your home volume be? EOF type = "number" default = 30 mutable = true order = 3 option { name = "30GB" value = 30 } option { name = "60GB" value = 60 } option { name = "100GB" value = 100 } validation { monotonic = "increasing" } } ``` ## Schema ### Required - `name` (String) The name of the parameter. If this is changed, developers will be re-prompted for a new value. ### Optional - `default` (String) A default value for the parameter. - `description` (String) Describe what this parameter does. - `display_name` (String) The displayed name of the parameter as it will appear in the interface. - `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds. - `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution! - `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option)) - `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order). - `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. - `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`. - `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation)) ### Read-Only - `id` (String) The ID of this resource. - `optional` (Boolean) Whether this value is optional. - `value` (String) The output value of the parameter. ### Nested Schema for `option` Required: - `name` (String) The display name of this value in the UI. - `value` (String) The value of this option set on the parameter if selected. Optional: - `description` (String) Describe what selecting this value does. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. ### Nested Schema for `validation` Optional: - `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`. - `max` (Number) The maximum value of a number parameter. - `min` (Number) The minimum value of a number parameter. - `monotonic` (String) Number monotonicity, either increasing or decreasing. - `regex` (String) A regex for the input parameter to match against. Read-Only: - `max_disabled` (Boolean) Helper field to check if `max` is present - `min_disabled` (Boolean) Helper field to check if `min` is present \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_parameter Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to configure editable options for workspaces. +--- + +# coder_parameter (Data Source) + +Use this data source to configure editable options for workspaces. + +## Example Usage + +```terraform +provider "coder" {} + +data "coder_parameter" "example" { + name = "Region" + description = "Specify a region to place your workspace." + mutable = false + type = "string" + default = "us-central1-a" + option { + value = "us-central1-a" + name = "US Central" + icon = "/icons/1f1fa-1f1f8.png" + } + option { + value = "asia-southeast1-a" + name = "Singapore" + icon = "/icons/1f1f8-1f1ec.png" + } +} + +data "coder_parameter" "ami" { + name = "Machine Image" + description = <<-EOT + # Provide the machine image + See the [registry](https://container.registry.blah/namespace) for options. + EOT + option { + value = "ami-xxxxxxxx" + name = "Ubuntu" + icon = "/icon/ubuntu.svg" + } +} + +data "coder_parameter" "is_public_instance" { + name = "Is public instance?" + type = "bool" + icon = "/icon/docker.svg" + default = false +} + +data "coder_parameter" "cores" { + name = "CPU Cores" + type = "number" + icon = "/icon/cpu.svg" + default = 3 + order = 10 +} + +data "coder_parameter" "disk_size" { + name = "Disk Size" + type = "number" + default = "5" + order = 8 + validation { + # This can apply to number. + min = 0 + max = 10 + monotonic = "increasing" + } +} + +data "coder_parameter" "cat_lives" { + name = "Cat Lives" + type = "number" + default = "9" + validation { + # This can apply to number. + min = 0 + max = 10 + monotonic = "decreasing" + } +} + +data "coder_parameter" "fairy_tale" { + name = "Fairy Tale" + type = "string" + mutable = true + default = "Hansel and Gretel" + ephemeral = true +} + +data "coder_parameter" "users" { + name = "system_users" + display_name = "System users" + type = "list(string)" + default = jsonencode(["root", "user1", "user2"]) +} + +data "coder_parameter" "home_volume_size" { + name = "Home Volume Size" + description = <<-EOF + How large should your home volume be? + EOF + type = "number" + default = 30 + mutable = true + order = 3 + + option { + name = "30GB" + value = 30 + } + + option { + name = "60GB" + value = 60 + } + + option { + name = "100GB" + value = 100 + } + + validation { + monotonic = "increasing" + } +} +``` + + +## Schema + +### Required + +- `name` (String) The name of the parameter. If this is changed, developers will be re-prompted for a new value. + +### Optional + +- `default` (String) A default value for the parameter. +- `description` (String) Describe what this parameter does. +- `display_name` (String) The displayed name of the parameter as it will appear in the interface. +- `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds. +- `form_type` (String) The type of this parameter. Must be one of: `"radio"`, `"slider"`, `"input"`, `"dropdown"`, `"checkbox"`, `"switch"`, `"multi-select"`, `"tag-select"`, `"textarea"`, `"error"`. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. +- `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution! +- `option` (Block List) Each `option` block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option)) +- `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order). +- `styling` (String) JSON encoded string containing the metadata for controlling the appearance of this parameter in the UI. This option is purely cosmetic and does not affect the function of the parameter in terraform. +- `type` (String) The type of this parameter. Must be one of: `"string"`, `"number"`, `"bool"`, `"list(string)"`. +- `validation` (Block List, Max: 1) Validate the input of a parameter. (see [below for nested schema](#nestedblock--validation)) + +### Read-Only + +- `id` (String) The ID of this resource. +- `optional` (Boolean) Whether this value is optional. +- `value` (String) The output value of the parameter. + + +### Nested Schema for `option` + +Required: + +- `name` (String) The display name of this value in the UI. +- `value` (String) The value of this option set on the parameter if selected. + +Optional: + +- `description` (String) Describe what selecting this value does. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. + + + +### Nested Schema for `validation` + +Optional: + +- `error` (String) An error message to display if the value breaks the validation rules. The following placeholders are supported: `{max}`, `{min}`, and `{value}`. +- `max` (Number) The maximum value of a number parameter. +- `min` (Number) The minimum value of a number parameter. +- `monotonic` (String) Number monotonicity, either increasing or decreasing. +- `regex` (String) A regex for the input parameter to match against. + +Read-Only: + +- `max_disabled` (Boolean) Helper field to check if `max` is present +- `min_disabled` (Boolean) Helper field to check if `min` is present diff --git a/docs/data-sources/provisioner.md b/docs/data-sources/provisioner.md index 7f584ec..a1ddbe7 100644 --- a/docs/data-sources/provisioner.md +++ b/docs/data-sources/provisioner.md @@ -1 +1,42 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_provisioner Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to get information about the Coder provisioner. --- # coder_provisioner (Data Source) Use this data source to get information about the Coder provisioner. ## Example Usage ```terraform provider "coder" {} data "coder_provisioner" "dev" {} data "coder_workspace" "dev" {} resource "coder_agent" "main" { arch = data.coder_provisioner.dev.arch os = data.coder_provisioner.dev.os dir = "/workspace" display_apps { vscode = true vscode_insiders = false web_terminal = true ssh_helper = false } } ``` ## Schema ### Read-Only - `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). - `id` (String) The ID of this resource. - `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_provisioner Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to get information about the Coder provisioner. +--- + +# coder_provisioner (Data Source) + +Use this data source to get information about the Coder provisioner. + +## Example Usage + +```terraform +provider "coder" {} + +data "coder_provisioner" "dev" {} + +data "coder_workspace" "dev" {} + +resource "coder_agent" "main" { + arch = data.coder_provisioner.dev.arch + os = data.coder_provisioner.dev.os + dir = "/workspace" + display_apps { + vscode = true + vscode_insiders = false + web_terminal = true + ssh_helper = false + } +} +``` + + +## Schema + +### Read-Only + +- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). +- `id` (String) The ID of this resource. +- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)). diff --git a/docs/data-sources/workspace.md b/docs/data-sources/workspace.md index d8e9d53..9b3266a 100644 --- a/docs/data-sources/workspace.md +++ b/docs/data-sources/workspace.md @@ -1 +1,80 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to get information for the active workspace build. --- # coder_workspace (Data Source) Use this data source to get information for the active workspace build. ## Example Usage ```terraform provider "coder" {} provider "docker" {} data "coder_workspace" "me" {} data "coder_workspace_owner" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" dir = "/workspace" } resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count image = docker_image.main.name # Uses lower() to avoid Docker restriction on container names. name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" # Hostname makes the shell more user friendly: coder@my-workspace:~$ hostname = data.coder_workspace.me.name # Use the docker gateway if the access URL is 127.0.0.1 entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")] env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] host { host = "host.docker.internal" ip = "host-gateway" } # Add labels in Docker to keep track of orphan resources. labels { label = "coder.owner" value = data.coder_workspace_owner.me.name } labels { label = "coder.owner_id" value = data.coder_workspace_owner.me.id } labels { label = "coder.workspace_id" value = data.coder_workspace.me.id } labels { label = "coder.workspace_name" value = data.coder_workspace.me.name } } ``` ## Schema ### Read-Only - `access_port` (Number) The access port of the Coder deployment provisioning this workspace. - `access_url` (String) The access URL of the Coder deployment provisioning this workspace. - `id` (String) UUID of the workspace. - `is_prebuild` (Boolean) Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false. - `is_prebuild_claim` (Boolean) Indicates whether a prebuilt workspace has just been claimed and this is the first `apply` after that occurrence. - `name` (String) Name of the workspace. - `prebuild_count` (Number) A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0. - `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1. - `template_id` (String) ID of the workspace's template. - `template_name` (String) Name of the workspace's template. - `template_version` (String) Version of the workspace's template. - `transition` (String) Either `start` or `stop`. Use this to start/stop resources with `count`. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_workspace Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to get information for the active workspace build. +--- + +# coder_workspace (Data Source) + +Use this data source to get information for the active workspace build. + +## Example Usage + +```terraform +provider "coder" {} + +provider "docker" {} + +data "coder_workspace" "me" {} + +data "coder_workspace_owner" "me" {} + +resource "coder_agent" "dev" { + arch = "amd64" + os = "linux" + dir = "/workspace" +} + +resource "docker_container" "workspace" { + count = data.coder_workspace.me.start_count + image = docker_image.main.name + # Uses lower() to avoid Docker restriction on container names. + name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" + # Hostname makes the shell more user friendly: coder@my-workspace:~$ + hostname = data.coder_workspace.me.name + # Use the docker gateway if the access URL is 127.0.0.1 + entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")] + env = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"] + host { + host = "host.docker.internal" + ip = "host-gateway" + } + # Add labels in Docker to keep track of orphan resources. + labels { + label = "coder.owner" + value = data.coder_workspace_owner.me.name + } + labels { + label = "coder.owner_id" + value = data.coder_workspace_owner.me.id + } + labels { + label = "coder.workspace_id" + value = data.coder_workspace.me.id + } + labels { + label = "coder.workspace_name" + value = data.coder_workspace.me.name + } +} +``` + + +## Schema + +### Read-Only + +- `access_port` (Number) The access port of the Coder deployment provisioning this workspace. +- `access_url` (String) The access URL of the Coder deployment provisioning this workspace. +- `id` (String) UUID of the workspace. +- `is_prebuild` (Boolean) Similar to `prebuild_count`, but a boolean value instead of a count. This is set to true if the workspace is a currently unassigned prebuild. Once the workspace is assigned, this value will be false. +- `is_prebuild_claim` (Boolean) Indicates whether a prebuilt workspace has just been claimed and this is the first `apply` after that occurrence. +- `name` (String) Name of the workspace. +- `prebuild_count` (Number) A computed count, equal to 1 if the workspace is a currently unassigned prebuild. Use this to conditionally act on the status of a prebuild. Actions that do not require user identity can be taken when this value is set to 1. Actions that should only be taken once the workspace has been assigned to a user may be taken when this value is set to 0. +- `start_count` (Number) A computed count based on `transition` state. If `start`, count will equal 1. +- `template_id` (String) ID of the workspace's template. +- `template_name` (String) Name of the workspace's template. +- `template_version` (String) Version of the workspace's template. +- `transition` (String) Either `start` or `stop`. Use this to start/stop resources with `count`. diff --git a/docs/data-sources/workspace_owner.md b/docs/data-sources/workspace_owner.md index 92559dd..b3f5779 100644 --- a/docs/data-sources/workspace_owner.md +++ b/docs/data-sources/workspace_owner.md @@ -1 +1,67 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_owner Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to fetch information about the workspace owner. --- # coder_workspace_owner (Data Source) Use this data source to fetch information about the workspace owner. ## Example Usage ```terraform provider "coder" {} data "coder_workspace_owner" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" dir = "/workspace" env = { OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token, } } # Add git credentials from coder_workspace_owner resource "coder_env" "git_author_name" { agent_id = coder_agent.agent_id name = "GIT_AUTHOR_NAME" value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name) } resource "coder_env" "git_author_email" { agent_id = coder_agent.dev.id name = "GIT_AUTHOR_EMAIL" value = data.coder_workspace_owner.me.email count = data.coder_workspace_owner.me.email != "" ? 1 : 0 } ``` ## Schema ### Read-Only - `email` (String) The email address of the user. - `full_name` (String) The full name of the user. - `groups` (List of String) The groups of which the user is a member. - `id` (String) The UUID of the workspace owner. - `login_type` (String) The type of login the user has. - `name` (String) The username of the user. - `oidc_access_token` (String) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string. - `rbac_roles` (List of Object) The RBAC roles of which the user is assigned. (see [below for nested schema](#nestedatt--rbac_roles)) - `session_token` (String) Session token for authenticating with a Coder deployment. It is regenerated every time a workspace is started. - `ssh_private_key` (String, Sensitive) The user's generated SSH private key. - `ssh_public_key` (String) The user's generated SSH public key. ### Nested Schema for `rbac_roles` Read-Only: - `name` (String) - `org_id` (String) \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_workspace_owner Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to fetch information about the workspace owner. +--- + +# coder_workspace_owner (Data Source) + +Use this data source to fetch information about the workspace owner. + +## Example Usage + +```terraform +provider "coder" {} + +data "coder_workspace_owner" "me" {} + +resource "coder_agent" "dev" { + arch = "amd64" + os = "linux" + dir = "/workspace" + env = { + OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token, + } +} + +# Add git credentials from coder_workspace_owner +resource "coder_env" "git_author_name" { + agent_id = coder_agent.agent_id + name = "GIT_AUTHOR_NAME" + value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name) +} + +resource "coder_env" "git_author_email" { + agent_id = coder_agent.dev.id + name = "GIT_AUTHOR_EMAIL" + value = data.coder_workspace_owner.me.email + count = data.coder_workspace_owner.me.email != "" ? 1 : 0 +} +``` + + +## Schema + +### Read-Only + +- `email` (String) The email address of the user. +- `full_name` (String) The full name of the user. +- `groups` (List of String) The groups of which the user is a member. +- `id` (String) The UUID of the workspace owner. +- `login_type` (String) The type of login the user has. +- `name` (String) The username of the user. +- `oidc_access_token` (String) A valid OpenID Connect access token of the workspace owner. This is only available if the workspace owner authenticated with OpenID Connect. If a valid token cannot be obtained, this value will be an empty string. +- `rbac_roles` (List of Object) The RBAC roles of which the user is assigned. (see [below for nested schema](#nestedatt--rbac_roles)) +- `session_token` (String) Session token for authenticating with a Coder deployment. It is regenerated every time a workspace is started. +- `ssh_private_key` (String, Sensitive) The user's generated SSH private key. +- `ssh_public_key` (String) The user's generated SSH public key. + + +### Nested Schema for `rbac_roles` + +Read-Only: + +- `name` (String) +- `org_id` (String) diff --git a/docs/data-sources/workspace_preset.md b/docs/data-sources/workspace_preset.md index 5d0d84c..383e753 100644 --- a/docs/data-sources/workspace_preset.md +++ b/docs/data-sources/workspace_preset.md @@ -1 +1,95 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_preset Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. --- # coder_workspace_preset (Data Source) Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. ## Example Usage ```terraform provider "coder" {} # presets can be used to predefine common configurations for workspaces # Parameters are referenced by their name. Each parameter must be defined in the preset. # Values defined by the preset must pass validation for the parameter. # See the coder_parameter data source's documentation for examples of how to define # parameters like the ones used below. data "coder_workspace_preset" "example" { name = "example" parameters = { (data.coder_parameter.example.name) = "us-central1-a" (data.coder_parameter.ami.name) = "ami-xxxxxxxx" } } # Example of a default preset that will be pre-selected for users data "coder_workspace_preset" "standard" { name = "Standard" default = true parameters = { (data.coder_parameter.instance_type.name) = "t3.medium" (data.coder_parameter.region.name) = "us-west-2" } } ``` ## Schema ### Required - `name` (String) The name of the workspace preset. ### Optional - `default` (Boolean) Whether this preset should be selected by default when creating a workspace. Only one preset per template can be marked as default. - `parameters` (Map of String) Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version. - `prebuilds` (Block Set, Max: 1) Configuration for prebuilt workspaces associated with this preset. Coder will maintain a pool of standby workspaces based on this configuration. When a user creates a workspace using this preset, they are assigned a prebuilt workspace instead of waiting for a new one to build. See prebuilt workspace documentation [here](https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces.md) (see [below for nested schema](#nestedblock--prebuilds)) ### Read-Only - `id` (String) The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset. ### Nested Schema for `prebuilds` Required: - `instances` (Number) The number of workspaces to keep in reserve for this preset. Optional: - `expiration_policy` (Block Set, Max: 1) Configuration block that defines TTL (time-to-live) behavior for prebuilds. Use this to automatically invalidate and delete prebuilds after a certain period, ensuring they stay up-to-date. (see [below for nested schema](#nestedblock--prebuilds--expiration_policy)) - `scheduling` (Block List, Max: 1) Configuration block that defines scheduling behavior for prebuilds. Use this to automatically adjust the number of prebuild instances based on a schedule. (see [below for nested schema](#nestedblock--prebuilds--scheduling)) ### Nested Schema for `prebuilds.expiration_policy` Required: - `ttl` (Number) Time in seconds after which an unclaimed prebuild is considered expired and eligible for cleanup. ### Nested Schema for `prebuilds.scheduling` Required: - `schedule` (Block List, Min: 1) One or more schedule blocks that define when to scale the number of prebuild instances. (see [below for nested schema](#nestedblock--prebuilds--scheduling--schedule)) - `timezone` (String) The timezone to use for the prebuild schedules (e.g., "UTC", "America/New_York"). Timezone must be a valid timezone in the IANA timezone database. See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a complete list of valid timezone identifiers and https://www.iana.org/time-zones for the official IANA timezone database. ### Nested Schema for `prebuilds.scheduling.schedule` Required: - `cron` (String) A cron expression that defines when this schedule should be active. The cron expression must be in the format "* HOUR DOM MONTH DAY-OF-WEEK" where HOUR is 0-23, DOM (day-of-month) is 1-31, MONTH is 1-12, and DAY-OF-WEEK is 0-6 (Sunday-Saturday). The minute field must be "*" to ensure the schedule covers entire hours rather than specific minute intervals. - `instances` (Number) The number of prebuild instances to maintain during this schedule period. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_workspace_preset Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. +--- + +# coder_workspace_preset (Data Source) + +Use this data source to predefine common configurations for coder workspaces. Users will have the option to select a defined preset, which will automatically apply the selected configuration. Any parameters defined in the preset will be applied to the workspace. Parameters that are defined by the template but not defined by the preset will still be configurable when creating a workspace. + +## Example Usage + +```terraform +provider "coder" {} + +# presets can be used to predefine common configurations for workspaces +# Parameters are referenced by their name. Each parameter must be defined in the preset. +# Values defined by the preset must pass validation for the parameter. +# See the coder_parameter data source's documentation for examples of how to define +# parameters like the ones used below. +data "coder_workspace_preset" "example" { + name = "example" + parameters = { + (data.coder_parameter.example.name) = "us-central1-a" + (data.coder_parameter.ami.name) = "ami-xxxxxxxx" + } +} + +# Example of a default preset that will be pre-selected for users +data "coder_workspace_preset" "standard" { + name = "Standard" + default = true + parameters = { + (data.coder_parameter.instance_type.name) = "t3.medium" + (data.coder_parameter.region.name) = "us-west-2" + } +} +``` + + +## Schema + +### Required + +- `name` (String) The name of the workspace preset. + +### Optional + +- `default` (Boolean) Whether this preset should be selected by default when creating a workspace. Only one preset per template can be marked as default. +- `parameters` (Map of String) Workspace parameters that will be set by the workspace preset. For simple templates that only need prebuilds, you may define a preset with zero parameters. Because workspace parameters may change between Coder template versions, preset parameters are allowed to define values for parameters that do not exist in the current template version. +- `prebuilds` (Block Set, Max: 1) Configuration for prebuilt workspaces associated with this preset. Coder will maintain a pool of standby workspaces based on this configuration. When a user creates a workspace using this preset, they are assigned a prebuilt workspace instead of waiting for a new one to build. See prebuilt workspace documentation [here](https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces.md) (see [below for nested schema](#nestedblock--prebuilds)) + +### Read-Only + +- `id` (String) The preset ID is automatically generated and may change between runs. It is recommended to use the `name` attribute to identify the preset. + + +### Nested Schema for `prebuilds` + +Required: + +- `instances` (Number) The number of workspaces to keep in reserve for this preset. + +Optional: + +- `expiration_policy` (Block Set, Max: 1) Configuration block that defines TTL (time-to-live) behavior for prebuilds. Use this to automatically invalidate and delete prebuilds after a certain period, ensuring they stay up-to-date. (see [below for nested schema](#nestedblock--prebuilds--expiration_policy)) +- `scheduling` (Block List, Max: 1) Configuration block that defines scheduling behavior for prebuilds. Use this to automatically adjust the number of prebuild instances based on a schedule. (see [below for nested schema](#nestedblock--prebuilds--scheduling)) + + +### Nested Schema for `prebuilds.expiration_policy` + +Required: + +- `ttl` (Number) Time in seconds after which an unclaimed prebuild is considered expired and eligible for cleanup. + + + +### Nested Schema for `prebuilds.scheduling` + +Required: + +- `schedule` (Block List, Min: 1) One or more schedule blocks that define when to scale the number of prebuild instances. (see [below for nested schema](#nestedblock--prebuilds--scheduling--schedule)) +- `timezone` (String) The timezone to use for the prebuild schedules (e.g., "UTC", "America/New_York"). +Timezone must be a valid timezone in the IANA timezone database. +See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a complete list of valid timezone identifiers and https://www.iana.org/time-zones for the official IANA timezone database. + + +### Nested Schema for `prebuilds.scheduling.schedule` + +Required: + +- `cron` (String) A cron expression that defines when this schedule should be active. The cron expression must be in the format "* HOUR DOM MONTH DAY-OF-WEEK" where HOUR is 0-23, DOM (day-of-month) is 1-31, MONTH is 1-12, and DAY-OF-WEEK is 0-6 (Sunday-Saturday). The minute field must be "*" to ensure the schedule covers entire hours rather than specific minute intervals. +- `instances` (Number) The number of prebuild instances to maintain during this schedule period. diff --git a/docs/data-sources/workspace_tags.md b/docs/data-sources/workspace_tags.md index 34c4a63..ef7835a 100644 --- a/docs/data-sources/workspace_tags.md +++ b/docs/data-sources/workspace_tags.md @@ -1 +1,77 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_workspace_tags Data Source - terraform-provider-coder" subcategory: "" description: |- Use this data source to configure workspace tags to select provisioners. --- # coder_workspace_tags (Data Source) Use this data source to configure workspace tags to select provisioners. ## Example Usage ```terraform provider "coder" {} data "coder_parameter" "os_selector" { name = "os_selector" display_name = "Operating System" mutable = false default = "osx" option { icon = "/icons/linux.png" name = "Linux" value = "linux" } option { icon = "/icons/osx.png" name = "OSX" value = "osx" } option { icon = "/icons/windows.png" name = "Windows" value = "windows" } } data "coder_parameter" "feature_cache_enabled" { name = "feature_cache_enabled" display_name = "Enable cache?" type = "bool" default = false } data "coder_parameter" "feature_debug_enabled" { name = "feature_debug_enabled" display_name = "Enable debug?" type = "bool" default = true } data "coder_workspace_tags" "custom_workspace_tags" { tags = { "cluster" = "developers" "os" = data.coder_parameter.os_selector.value "debug" = "${data.coder_parameter.feature_debug_enabled.value}+12345" "cache" = data.coder_parameter.feature_cache_enabled.value == "true" ? "nix-with-cache" : "no-cache" } } ``` ## Schema ### Optional - `tags` (Map of String) Key-value map with workspace tags ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_workspace_tags Data Source - terraform-provider-coder" +subcategory: "" +description: |- + Use this data source to configure workspace tags to select provisioners. +--- + +# coder_workspace_tags (Data Source) + +Use this data source to configure workspace tags to select provisioners. + +## Example Usage + +```terraform +provider "coder" {} + +data "coder_parameter" "os_selector" { + name = "os_selector" + display_name = "Operating System" + mutable = false + + default = "osx" + + option { + icon = "/icons/linux.png" + name = "Linux" + value = "linux" + } + option { + icon = "/icons/osx.png" + name = "OSX" + value = "osx" + } + option { + icon = "/icons/windows.png" + name = "Windows" + value = "windows" + } +} + +data "coder_parameter" "feature_cache_enabled" { + name = "feature_cache_enabled" + display_name = "Enable cache?" + type = "bool" + + default = false +} + +data "coder_parameter" "feature_debug_enabled" { + name = "feature_debug_enabled" + display_name = "Enable debug?" + type = "bool" + + default = true +} + +data "coder_workspace_tags" "custom_workspace_tags" { + tags = { + "cluster" = "developers" + "os" = data.coder_parameter.os_selector.value + "debug" = "${data.coder_parameter.feature_debug_enabled.value}+12345" + "cache" = data.coder_parameter.feature_cache_enabled.value == "true" ? "nix-with-cache" : "no-cache" + } +} +``` + + +## Schema + +### Optional + +- `tags` (Map of String) Key-value map with workspace tags + +### Read-Only + +- `id` (String) The ID of this resource. diff --git a/docs/index.md b/docs/index.md index 62eab1e..bb97ff1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1 +1,77 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "Coder Provider" subcategory: "Infrastructure" description: |- Terraform provider for managing Coder templates, which are the underlying infrastructure for Coder workspaces. --- # Coder Provider Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). -> Requires Coder [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. !> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. ## Version Compatibility This provider automatically documents version requirements for individual resources and features. ~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. ## Example ```terraform terraform { required_providers { coder = { source = "coder/coder" } } } provider "google" { region = "us-central1" } data "coder_workspace" "me" {} resource "coder_agent" "dev" { arch = "amd64" os = "linux" auth = "google-instance-identity" } data "google_compute_default_service_account" "default" {} resource "google_compute_instance" "dev" { zone = "us-central1-a" count = data.coder_workspace.me.start_count name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" machine_type = "e2-medium" network_interface { network = "default" access_config { // Ephemeral public IP } } boot_disk { initialize_params { image = "debian-cloud/debian-9" } } service_account { email = data.google_compute_default_service_account.default.email scopes = ["cloud-platform"] } metadata_startup_script = coder_agent.dev.init_script } ``` ## Schema ### Optional - `url` (String) The URL to access Coder. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "Coder Provider" +subcategory: "Infrastructure" +description: |- + Terraform provider for managing Coder templates, which are the underlying infrastructure for Coder workspaces. +--- + +# Coder Provider + +Terraform provider for managing Coder [templates](https://coder.com/docs/admin/templates), which are the underlying infrastructure for Coder [workspaces](https://coder.com/docs/user-guides/workspace-management). + +-> Requires Coder [v2.18.0](https://github.com/coder/coder/releases/tag/v2.18.0) or later. + +!> [`coder_git_auth`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/git_auth) and owner related fields of [`coder_workspace`](https://registry.terraform.io/providers/coder/coder/1.0.4/docs/data-sources/workspace) data source have been removed. Follow the [Version 2 Upgrade Guide](https://registry.terraform.io/providers/coder/coder/latest/docs/guides/version-2-upgrade) to update your code. + +## Version Compatibility + +This provider automatically documents version requirements for individual resources and features. + +~> **Note:** Individual resources may have higher version requirements. Check the documentation for each resource to see its specific minimum Coder version. + +## Example + +```terraform +terraform { + required_providers { + coder = { + source = "coder/coder" + } + } +} + +provider "google" { + region = "us-central1" +} + +data "coder_workspace" "me" {} + +resource "coder_agent" "dev" { + arch = "amd64" + os = "linux" + auth = "google-instance-identity" +} + +data "google_compute_default_service_account" "default" {} + +resource "google_compute_instance" "dev" { + zone = "us-central1-a" + count = data.coder_workspace.me.start_count + name = "coder-${data.coder_workspace.me.owner}-${data.coder_workspace.me.name}" + machine_type = "e2-medium" + network_interface { + network = "default" + access_config { + // Ephemeral public IP + } + } + boot_disk { + initialize_params { + image = "debian-cloud/debian-9" + } + } + service_account { + email = data.google_compute_default_service_account.default.email + scopes = ["cloud-platform"] + } + metadata_startup_script = coder_agent.dev.init_script +} +``` + + +## Schema + +### Optional + +- `url` (String) The URL to access Coder. \ No newline at end of file diff --git a/docs/resources/agent.md b/docs/resources/agent.md index b635f0a..64b7d84 100644 --- a/docs/resources/agent.md +++ b/docs/resources/agent.md @@ -1 +1,148 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_agent Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to associate an agent. --- # coder_agent (Resource) Use this resource to associate an agent. ## Example Usage ```terraform data "coder_workspace" "me" { } resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" api_key_scope = "all" display_apps { vscode = true vscode_insiders = false web_terminal = true ssh_helper = false } metadata { display_name = "CPU Usage" key = "cpu_usage" script = "coder stat cpu" interval = 10 timeout = 1 order = 2 } metadata { display_name = "RAM Usage" key = "ram_usage" script = "coder stat mem" interval = 10 timeout = 1 order = 1 } order = 1 } resource "kubernetes_pod" "dev" { count = data.coder_workspace.me.start_count spec { container { command = ["sh", "-c", coder_agent.dev.init_script] env { name = "CODER_AGENT_TOKEN" value = coder_agent.dev.token } } } } ``` ## Schema ### Required - `arch` (String) The architecture the agent will run on. Must be one of: `"amd64"`, `"armv7"`, `"arm64"`. - `os` (String) The operating system the agent will run on. Must be one of: `"linux"`, `"darwin"`, or `"windows"`. ### Optional - `api_key_scope` (String) Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes) - `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`. - `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out. - `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`. - `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps)) - `env` (Map of String) A mapping of environment variables to set inside the workspace. - `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata)) - `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be `"/etc/motd"`. - `order` (Number) The order determines the position of agents in the UI presentation. The lowest order is shown first and agents with equal order are sorted by name (ascending order). - `resources_monitoring` (Block Set, Max: 1) The resources monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring)) - `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a `coder_script` resource with `run_on_stop` set to `true`. - `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a `coder_script` resource with `run_on_start` set to `true`. - `startup_script_behavior` (String) This option sets the behavior of the `startup_script`. When set to `"blocking"`, the `startup_script` must exit before the workspace is ready. When set to `"non-blocking"`, the `startup_script` may run in the background and the workspace will be ready immediately. Default is `"non-blocking"`, although `"blocking"` is recommended. This option is an alias for defining a `coder_script` resource with `start_blocks_login` set to `true` (blocking). - `troubleshooting_url` (String) A URL to a document with instructions for troubleshooting problems with the agent. ### Read-Only - `id` (String) The ID of this resource. - `init_script` (String) Run this script on startup of an instance to initialize the agent. - `token` (String, Sensitive) Set the environment variable `CODER_AGENT_TOKEN` with this token to authenticate an agent. ### Nested Schema for `display_apps` Optional: - `port_forwarding_helper` (Boolean) Display the port-forwarding helper button in the agent bar. - `ssh_helper` (Boolean) Display the SSH helper button in the agent bar. - `vscode` (Boolean) Display the VSCode Desktop app in the agent bar. - `vscode_insiders` (Boolean) Display the VSCode Insiders app in the agent bar. - `web_terminal` (Boolean) Display the web terminal app in the agent bar. ### Nested Schema for `metadata` Required: - `interval` (Number) The interval in seconds at which to refresh this metadata item. - `key` (String) The key of this metadata item. - `script` (String) The script that retrieves the value of this metadata item. Optional: - `display_name` (String) The user-facing name of this value. - `order` (Number) The order determines the position of agent metadata in the UI presentation. The lowest order is shown first and metadata with equal order are sorted by key (ascending order). - `timeout` (Number) The maximum time the command is allowed to run in seconds. ### Nested Schema for `resources_monitoring` Optional: - `memory` (Block Set, Max: 1) The memory monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--memory)) - `volume` (Block Set) The volumes monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--volume)) ### Nested Schema for `resources_monitoring.memory` Required: - `enabled` (Boolean) Enable memory monitoring for this agent. - `threshold` (Number) The memory usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. ### Nested Schema for `resources_monitoring.volume` Required: - `enabled` (Boolean) Enable volume monitoring for this agent. - `path` (String) The path of the volume to monitor. - `threshold` (Number) The volume usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_agent Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to associate an agent. +--- + +# coder_agent (Resource) + +Use this resource to associate an agent. + +## Example Usage + +```terraform +data "coder_workspace" "me" { +} + +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" + dir = "/workspace" + api_key_scope = "all" + display_apps { + vscode = true + vscode_insiders = false + web_terminal = true + ssh_helper = false + } + + metadata { + display_name = "CPU Usage" + key = "cpu_usage" + script = "coder stat cpu" + interval = 10 + timeout = 1 + order = 2 + } + metadata { + display_name = "RAM Usage" + key = "ram_usage" + script = "coder stat mem" + interval = 10 + timeout = 1 + order = 1 + } + + order = 1 +} + +resource "kubernetes_pod" "dev" { + count = data.coder_workspace.me.start_count + spec { + container { + command = ["sh", "-c", coder_agent.dev.init_script] + env { + name = "CODER_AGENT_TOKEN" + value = coder_agent.dev.token + } + } + } +} +``` + + +## Schema + +### Required + +- `arch` (String) The architecture the agent will run on. Must be one of: `"amd64"`, `"armv7"`, `"arm64"`. +- `os` (String) The operating system the agent will run on. Must be one of: `"linux"`, `"darwin"`, or `"windows"`. + +### Optional + +- `api_key_scope` (String) Controls what API routes the agent token can access. Options: `all` (full access) or `no_user_data` (blocks `/external-auth`, `/gitsshkey`, and `/gitauth` routes) +- `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`. +- `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out. +- `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`. +- `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps)) +- `env` (Map of String) A mapping of environment variables to set inside the workspace. +- `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata)) +- `motd_file` (String) The path to a file within the workspace containing a message to display to users when they login via SSH. A typical value would be `"/etc/motd"`. +- `order` (Number) The order determines the position of agents in the UI presentation. The lowest order is shown first and agents with equal order are sorted by name (ascending order). +- `resources_monitoring` (Block Set, Max: 1) The resources monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring)) +- `shutdown_script` (String) A script to run before the agent is stopped. The script should exit when it is done to signal that the workspace can be stopped. This option is an alias for defining a `coder_script` resource with `run_on_stop` set to `true`. +- `startup_script` (String) A script to run after the agent starts. The script should exit when it is done to signal that the agent is ready. This option is an alias for defining a `coder_script` resource with `run_on_start` set to `true`. +- `startup_script_behavior` (String) This option sets the behavior of the `startup_script`. When set to `"blocking"`, the `startup_script` must exit before the workspace is ready. When set to `"non-blocking"`, the `startup_script` may run in the background and the workspace will be ready immediately. Default is `"non-blocking"`, although `"blocking"` is recommended. This option is an alias for defining a `coder_script` resource with `start_blocks_login` set to `true` (blocking). +- `troubleshooting_url` (String) A URL to a document with instructions for troubleshooting problems with the agent. + +### Read-Only + +- `id` (String) The ID of this resource. +- `init_script` (String) Run this script on startup of an instance to initialize the agent. +- `token` (String, Sensitive) Set the environment variable `CODER_AGENT_TOKEN` with this token to authenticate an agent. + + +### Nested Schema for `display_apps` + +Optional: + +- `port_forwarding_helper` (Boolean) Display the port-forwarding helper button in the agent bar. +- `ssh_helper` (Boolean) Display the SSH helper button in the agent bar. +- `vscode` (Boolean) Display the VSCode Desktop app in the agent bar. +- `vscode_insiders` (Boolean) Display the VSCode Insiders app in the agent bar. +- `web_terminal` (Boolean) Display the web terminal app in the agent bar. + + + +### Nested Schema for `metadata` + +Required: + +- `interval` (Number) The interval in seconds at which to refresh this metadata item. +- `key` (String) The key of this metadata item. +- `script` (String) The script that retrieves the value of this metadata item. + +Optional: + +- `display_name` (String) The user-facing name of this value. +- `order` (Number) The order determines the position of agent metadata in the UI presentation. The lowest order is shown first and metadata with equal order are sorted by key (ascending order). +- `timeout` (Number) The maximum time the command is allowed to run in seconds. + + + +### Nested Schema for `resources_monitoring` + +Optional: + +- `memory` (Block Set, Max: 1) The memory monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--memory)) +- `volume` (Block Set) The volumes monitoring configuration for this agent. (see [below for nested schema](#nestedblock--resources_monitoring--volume)) + + +### Nested Schema for `resources_monitoring.memory` + +Required: + +- `enabled` (Boolean) Enable memory monitoring for this agent. +- `threshold` (Number) The memory usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. + + + +### Nested Schema for `resources_monitoring.volume` + +Required: + +- `enabled` (Boolean) Enable volume monitoring for this agent. +- `path` (String) The path of the volume to monitor. +- `threshold` (Number) The volume usage threshold in percentage at which to trigger an alert. Value should be between 0 and 100. diff --git a/docs/resources/agent_instance.md b/docs/resources/agent_instance.md index ffcdc66..063f691 100644 --- a/docs/resources/agent_instance.md +++ b/docs/resources/agent_instance.md @@ -1 +1,42 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_agent_instance Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for "google_compute_instance", "aws_instance", "azurerm_linux_virtual_machine", and "azurerm_windows_virtual_machine" resources. --- # coder_agent_instance (Resource) Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. ## Example Usage ```terraform resource "coder_agent" "dev" { os = "linux" arch = "amd64" auth = "google-instance-identity" } resource "google_compute_instance" "dev" { zone = "us-central1-a" } resource "coder_agent_instance" "dev" { agent_id = coder_agent.dev.id instance_id = google_compute_instance.dev.instance_id } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `instance_id` (String) The instance identifier of a provisioned resource. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_agent_instance Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for "google_compute_instance", "aws_instance", "azurerm_linux_virtual_machine", and "azurerm_windows_virtual_machine" resources. +--- + +# coder_agent_instance (Resource) + +Use this resource to associate an instance ID with an agent for zero-trust authentication. This association is done automatically for `"google_compute_instance"`, `"aws_instance"`, `"azurerm_linux_virtual_machine"`, and `"azurerm_windows_virtual_machine"` resources. + +## Example Usage + +```terraform +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" + auth = "google-instance-identity" +} + +resource "google_compute_instance" "dev" { + zone = "us-central1-a" +} + +resource "coder_agent_instance" "dev" { + agent_id = coder_agent.dev.id + instance_id = google_compute_instance.dev.instance_id +} +``` + + +## Schema + +### Required + +- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. +- `instance_id` (String) The instance identifier of a provisioned resource. + +### Read-Only + +- `id` (String) The ID of this resource. diff --git a/docs/resources/ai_task.md b/docs/resources/ai_task.md index 7a8b1a5..3002e96 100644 --- a/docs/resources/ai_task.md +++ b/docs/resources/ai_task.md @@ -1 +1,31 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_ai_task Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to define Coder tasks. --- # coder_ai_task (Resource) Use this resource to define Coder tasks. ## Schema ### Required - `sidebar_app` (Block Set, Min: 1, Max: 1) The coder_app to display in the sidebar. Usually a chat interface with the AI agent running in the workspace, like https://github.com/coder/agentapi. (see [below for nested schema](#nestedblock--sidebar_app)) ### Read-Only - `id` (String) A unique identifier for this resource. ### Nested Schema for `sidebar_app` Required: - `id` (String) A reference to an existing `coder_app` resource in your template. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_ai_task Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to define Coder tasks. +--- + +# coder_ai_task (Resource) + +Use this resource to define Coder tasks. + + + + +## Schema + +### Required + +- `sidebar_app` (Block Set, Min: 1, Max: 1) The coder_app to display in the sidebar. Usually a chat interface with the AI agent running in the workspace, like https://github.com/coder/agentapi. (see [below for nested schema](#nestedblock--sidebar_app)) + +### Read-Only + +- `id` (String) A unique identifier for this resource. + + +### Nested Schema for `sidebar_app` + +Required: + +- `id` (String) A reference to an existing `coder_app` resource in your template. diff --git a/docs/resources/app.md b/docs/resources/app.md index 47aebf9..242d166 100644 --- a/docs/resources/app.md +++ b/docs/resources/app.md @@ -1 +1,87 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_app Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to define shortcuts to access applications in a workspace. --- # coder_app (Resource) Use this resource to define shortcuts to access applications in a workspace. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" startup_script = < ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `slug` (String) A hostname-friendly name for the app. This is used in URLs to access the app. May contain alphanumerics and hyphens. Cannot start/end with a hyphen or contain two consecutive hyphens. ### Optional - `command` (String) A command to run in a terminal opening this app. In the web, this will open in a new tab. In the CLI, this will SSH and execute the command. Either `command` or `url` may be specified, but not both. - `display_name` (String) A display name to identify the app. Defaults to the slug. - `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. - `group` (String) The name of a group that this app belongs to. - `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) - `hidden` (Boolean) Determines if the app is visible in the UI. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. - `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). - `share` (String) Determines the level which the application is shared at. Valid levels are `"owner"` (default), `"authenticated"` and `"public"`. Level `"owner"` disables sharing on the app, so only the workspace owner can access it. Level `"authenticated"` shares the app with all authenticated users. Level `"public"` shares it with any user, including unauthenticated users. Permitted application sharing levels can be configured site-wide via a flag on `coder server` (Enterprise only). - `subdomain` (Boolean) Determines whether the app will be accessed via it's own subdomain or whether it will be accessed via a path on Coder. If wildcards have not been setup by the administrator then apps with `subdomain` set to `true` will not be accessible. Defaults to `false`. - `url` (String) An external url if `external=true` or a URL to be proxied to from inside the workspace. This should be of the form `http://localhost:PORT[/SUBPATH]`. Either `command` or `url` may be specified, but not both. ### Read-Only - `id` (String) The ID of this resource. ### Nested Schema for `healthcheck` Required: - `interval` (Number) Duration in seconds to wait between healthcheck requests. - `threshold` (Number) Number of consecutive heathcheck failures before returning an unhealthy status. - `url` (String) HTTP address used determine the application readiness. A successful health check is a HTTP response code less than 500 returned before `healthcheck.interval` seconds. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_app Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to define shortcuts to access applications in a workspace. +--- + +# coder_app (Resource) + +Use this resource to define shortcuts to access applications in a workspace. + +## Example Usage + +```terraform +data "coder_workspace" "me" {} + +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" + dir = "/workspace" + startup_script = < +## Schema + +### Required + +- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. +- `slug` (String) A hostname-friendly name for the app. This is used in URLs to access the app. May contain alphanumerics and hyphens. Cannot start/end with a hyphen or contain two consecutive hyphens. + +### Optional + +- `command` (String) A command to run in a terminal opening this app. In the web, this will open in a new tab. In the CLI, this will SSH and execute the command. Either `command` or `url` may be specified, but not both. +- `display_name` (String) A display name to identify the app. Defaults to the slug. +- `external` (Boolean) Specifies whether `url` is opened on the client machine instead of proxied through the workspace. +- `group` (String) The name of a group that this app belongs to. +- `healthcheck` (Block Set, Max: 1) HTTP health checking to determine the application readiness. (see [below for nested schema](#nestedblock--healthcheck)) +- `hidden` (Boolean) Determines if the app is visible in the UI. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. +- `open_in` (String) Determines where the app will be opened. Valid values are `"tab"` and `"slim-window" (default)`. `"tab"` opens in a new tab in the same browser window. `"slim-window"` opens a new browser window without navigation controls. +- `order` (Number) The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order). +- `share` (String) Determines the level which the application is shared at. Valid levels are `"owner"` (default), `"authenticated"` and `"public"`. Level `"owner"` disables sharing on the app, so only the workspace owner can access it. Level `"authenticated"` shares the app with all authenticated users. Level `"public"` shares it with any user, including unauthenticated users. Permitted application sharing levels can be configured site-wide via a flag on `coder server` (Enterprise only). +- `subdomain` (Boolean) Determines whether the app will be accessed via it's own subdomain or whether it will be accessed via a path on Coder. If wildcards have not been setup by the administrator then apps with `subdomain` set to `true` will not be accessible. Defaults to `false`. +- `url` (String) An external url if `external=true` or a URL to be proxied to from inside the workspace. This should be of the form `http://localhost:PORT[/SUBPATH]`. Either `command` or `url` may be specified, but not both. + +### Read-Only + +- `id` (String) The ID of this resource. + + +### Nested Schema for `healthcheck` + +Required: + +- `interval` (Number) Duration in seconds to wait between healthcheck requests. +- `threshold` (Number) Number of consecutive heathcheck failures before returning an unhealthy status. +- `url` (String) HTTP address used determine the application readiness. A successful health check is a HTTP response code less than 500 returned before `healthcheck.interval` seconds. diff --git a/docs/resources/devcontainer.md b/docs/resources/devcontainer.md index dbbd4c7..4e28221 100644 --- a/docs/resources/devcontainer.md +++ b/docs/resources/devcontainer.md @@ -1,3 +1,31 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_devcontainer Resource - terraform-provider-coder" subcategory: "" description: |- Define a Dev Container the agent should know of and attempt to autostart. --- # coder_devcontainer (Resource) Define a Dev Container the agent should know of and attempt to autostart. ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `workspace_folder` (String) The workspace folder to for the Dev Container. ### Optional - `config_path` (String) The path to the Dev Container configuration file (devcontainer.json). ### Read-Only - `id` (String) The ID of this resource. +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_devcontainer Resource - terraform-provider-coder" +subcategory: "" +description: |- + Define a Dev Container the agent should know of and attempt to autostart. +--- -~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. \ No newline at end of file +# coder_devcontainer (Resource) + +Define a Dev Container the agent should know of and attempt to autostart. + +~> **Note:** This resource requires [Coder v2.21.0](https://github.com/coder/coder/releases/tag/v2.21.0) or later. + + + + +## Schema + +### Required + +- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. +- `workspace_folder` (String) The workspace folder to for the Dev Container. + +### Optional + +- `config_path` (String) The path to the Dev Container configuration file (devcontainer.json). + +### Read-Only + +- `id` (String) The ID of this resource. diff --git a/docs/resources/env.md b/docs/resources/env.md index b6947d0..667234b 100644 --- a/docs/resources/env.md +++ b/docs/resources/env.md @@ -1 +1,51 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_env Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the coder_agent resource. --- # coder_env (Resource) Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" } resource "coder_env" "welcome_message" { agent_id = coder_agent.dev.id name = "WELCOME_MESSAGE" value = "Welcome to your Coder workspace!" } resource "coder_env" "internal_api_url" { agent_id = coder_agent.dev.id name = "INTERNAL_API_URL" value = "https://api.internal.company.com/v1" } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `name` (String) The name of the environment variable. ### Optional - `value` (String) The value of the environment variable. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_env Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the coder_agent resource. +--- + +# coder_env (Resource) + +Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the `coder_agent` resource. + +## Example Usage + +```terraform +data "coder_workspace" "me" {} + +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" + dir = "/workspace" +} + +resource "coder_env" "welcome_message" { + agent_id = coder_agent.dev.id + name = "WELCOME_MESSAGE" + value = "Welcome to your Coder workspace!" +} + +resource "coder_env" "internal_api_url" { + agent_id = coder_agent.dev.id + name = "INTERNAL_API_URL" + value = "https://api.internal.company.com/v1" +} +``` + + +## Schema + +### Required + +- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. +- `name` (String) The name of the environment variable. + +### Optional + +- `value` (String) The value of the environment variable. + +### Read-Only + +- `id` (String) The ID of this resource. diff --git a/docs/resources/metadata.md b/docs/resources/metadata.md index 26daf42..037f976 100644 --- a/docs/resources/metadata.md +++ b/docs/resources/metadata.md @@ -1 +1,92 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_metadata Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. Alternatively, to attach metadata to the agent, use a metadata block within a coder_agent resource. --- # coder_metadata (Resource) Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. ## Example Usage ```terraform data "coder_workspace" "me" { } resource "kubernetes_pod" "dev" { count = data.coder_workspace.me.start_count metadata { name = "k8s_example" namespace = "example" } spec { # Draw the rest of the pod! } } resource "tls_private_key" "example_key_pair" { algorithm = "ECDSA" ecdsa_curve = "P256" } resource "coder_metadata" "pod_info" { count = data.coder_workspace.me.start_count resource_id = kubernetes_pod.dev[0].id # (Enterprise-only) this resource consumes 200 quota units daily_cost = 200 item { key = "description" value = "This description will show up in the Coder dashboard." } item { key = "pod_uid" value = kubernetes_pod.dev[0].uid } item { key = "public_key" value = tls_private_key.example_key_pair.public_key_openssh # The value of this item will be hidden from view by default sensitive = true } } ``` ## Schema ### Required - `resource_id` (String) The `id` property of another resource that metadata should be attached to. ### Optional - `daily_cost` (Number) (Enterprise) The cost of this resource every 24 hours. Use the smallest denomination of your preferred currency. For example, if you work in USD, use cents. - `hide` (Boolean) Hide the resource from the UI. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `item` (Block List) Each `item` block defines a single metadata item consisting of a key/value pair. (see [below for nested schema](#nestedblock--item)) ### Read-Only - `id` (String) The ID of this resource. ### Nested Schema for `item` Required: - `key` (String) The key of this metadata item. Optional: - `sensitive` (Boolean) Set to `true` to for items such as API keys whose values should be hidden from view by default. Note that this does not prevent metadata from being retrieved using the API, so it is not suitable for secrets that should not be exposed to workspace users. - `value` (String) The value of this metadata item. Supports basic Markdown, including hyperlinks. Read-Only: - `is_null` (Boolean) \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_metadata Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. + Alternatively, to attach metadata to the agent, use a metadata block within a coder_agent resource. +--- + +# coder_metadata (Resource) + +Use this resource to attach metadata to a resource. They will be displayed in the Coder dashboard alongside the resource. The resource containing the agent, and it's metadata, will be shown by default. + +Alternatively, to attach metadata to the agent, use a `metadata` block within a `coder_agent` resource. + +## Example Usage + +```terraform +data "coder_workspace" "me" { +} + +resource "kubernetes_pod" "dev" { + count = data.coder_workspace.me.start_count + metadata { + name = "k8s_example" + namespace = "example" + } + spec { + # Draw the rest of the pod! + } +} + +resource "tls_private_key" "example_key_pair" { + algorithm = "ECDSA" + ecdsa_curve = "P256" +} + +resource "coder_metadata" "pod_info" { + count = data.coder_workspace.me.start_count + resource_id = kubernetes_pod.dev[0].id + # (Enterprise-only) this resource consumes 200 quota units + daily_cost = 200 + item { + key = "description" + value = "This description will show up in the Coder dashboard." + } + item { + key = "pod_uid" + value = kubernetes_pod.dev[0].uid + } + item { + key = "public_key" + value = tls_private_key.example_key_pair.public_key_openssh + # The value of this item will be hidden from view by default + sensitive = true + } +} +``` + + +## Schema + +### Required + +- `resource_id` (String) The `id` property of another resource that metadata should be attached to. + +### Optional + +- `daily_cost` (Number) (Enterprise) The cost of this resource every 24 hours. Use the smallest denomination of your preferred currency. For example, if you work in USD, use cents. +- `hide` (Boolean) Hide the resource from the UI. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. +- `item` (Block List) Each `item` block defines a single metadata item consisting of a key/value pair. (see [below for nested schema](#nestedblock--item)) + +### Read-Only + +- `id` (String) The ID of this resource. + + +### Nested Schema for `item` + +Required: + +- `key` (String) The key of this metadata item. + +Optional: + +- `sensitive` (Boolean) Set to `true` to for items such as API keys whose values should be hidden from view by default. Note that this does not prevent metadata from being retrieved using the API, so it is not suitable for secrets that should not be exposed to workspace users. +- `value` (String) The value of this metadata item. Supports basic Markdown, including hyperlinks. + +Read-Only: + +- `is_null` (Boolean) diff --git a/docs/resources/script.md b/docs/resources/script.md index ef77d5b..39b8808 100644 --- a/docs/resources/script.md +++ b/docs/resources/script.md @@ -1 +1,91 @@ ---- # generated by https://github.com/hashicorp/terraform-plugin-docs page_title: "coder_script Resource - terraform-provider-coder" subcategory: "" description: |- Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. --- # coder_script (Resource) Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. ## Example Usage ```terraform data "coder_workspace" "me" {} resource "coder_agent" "dev" { os = "linux" arch = "amd64" dir = "/workspace" } resource "coder_script" "dotfiles" { agent_id = coder_agent.dev.agent_id display_name = "Dotfiles" icon = "/icon/dotfiles.svg" run_on_start = true script = templatefile("~/get_dotfiles.sh", { DOTFILES_URI : var.dotfiles_uri, DOTFILES_USER : var.dotfiles_user }) } resource "coder_script" "code-server" { agent_id = coder_agent.dev.agent_id display_name = "code-server" icon = "/icon/code.svg" run_on_start = true start_blocks_login = true script = templatefile("./install-code-server.sh", { LOG_PATH : "/tmp/code-server.log" }) } resource "coder_script" "nightly_sleep_reminder" { agent_id = coder_agent.dev.agent_id display_name = "Nightly update" icon = "/icon/database.svg" cron = "0 22 * * *" script = </tmp/pid.log 2>&1 & EOF } ``` ## Schema ### Required - `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. - `display_name` (String) The display name of the script to display logs in the dashboard. - `script` (String) The content of the script that will be run. ### Optional - `cron` (String) The cron schedule to run the script on. This is a cron expression. - `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. - `log_path` (String) The path of a file to write the logs to. If relative, it will be appended to tmp. - `run_on_start` (Boolean) This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready. - `run_on_stop` (Boolean) This option defines whether or not the script should run when the agent stops. The script should exit when it is done to signal that the workspace can be stopped. - `start_blocks_login` (Boolean) This option determines whether users can log in immediately or must wait for the workspace to finish running this script upon startup. If not enabled, users may encounter an incomplete workspace when logging in. This option only sets the default, the user can still manually override the behavior. - `timeout` (Number) Time in seconds that the script is allowed to run. If the script does not complete within this time, the script is terminated and the agent lifecycle status is marked as timed out. A value of zero (default) means no timeout. ### Read-Only - `id` (String) The ID of this resource. \ No newline at end of file +--- +# generated by https://github.com/hashicorp/terraform-plugin-docs +page_title: "coder_script Resource - terraform-provider-coder" +subcategory: "" +description: |- + Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. +--- + +# coder_script (Resource) + +Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel. + +## Example Usage + +```terraform +data "coder_workspace" "me" {} + +resource "coder_agent" "dev" { + os = "linux" + arch = "amd64" + dir = "/workspace" +} + +resource "coder_script" "dotfiles" { + agent_id = coder_agent.dev.agent_id + display_name = "Dotfiles" + icon = "/icon/dotfiles.svg" + run_on_start = true + script = templatefile("~/get_dotfiles.sh", { + DOTFILES_URI : var.dotfiles_uri, + DOTFILES_USER : var.dotfiles_user + }) +} + +resource "coder_script" "code-server" { + agent_id = coder_agent.dev.agent_id + display_name = "code-server" + icon = "/icon/code.svg" + run_on_start = true + start_blocks_login = true + script = templatefile("./install-code-server.sh", { + LOG_PATH : "/tmp/code-server.log" + }) +} + +resource "coder_script" "nightly_sleep_reminder" { + agent_id = coder_agent.dev.agent_id + display_name = "Nightly update" + icon = "/icon/database.svg" + cron = "0 22 * * *" + script = </tmp/pid.log 2>&1 & + EOF +} +``` + + +## Schema + +### Required + +- `agent_id` (String) The `id` property of a `coder_agent` resource to associate with. +- `display_name` (String) The display name of the script to display logs in the dashboard. +- `script` (String) The content of the script that will be run. + +### Optional + +- `cron` (String) The cron schedule to run the script on. This is a cron expression. +- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `"${data.coder_workspace.me.access_url}/icon/"`. +- `log_path` (String) The path of a file to write the logs to. If relative, it will be appended to tmp. +- `run_on_start` (Boolean) This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready. +- `run_on_stop` (Boolean) This option defines whether or not the script should run when the agent stops. The script should exit when it is done to signal that the workspace can be stopped. +- `start_blocks_login` (Boolean) This option determines whether users can log in immediately or must wait for the workspace to finish running this script upon startup. If not enabled, users may encounter an incomplete workspace when logging in. This option only sets the default, the user can still manually override the behavior. +- `timeout` (Number) Time in seconds that the script is allowed to run. If the script does not complete within this time, the script is terminated and the agent lifecycle status is marked as timed out. A value of zero (default) means no timeout. + +### Read-Only + +- `id` (String) The ID of this resource. diff --git a/scripts/docsgen/main.go b/scripts/docsgen/main.go index cc0456a..425ed02 100644 --- a/scripts/docsgen/main.go +++ b/scripts/docsgen/main.go @@ -110,10 +110,12 @@ func writeDeprecationMessage(doc []byte, schemas map[string]*schema.Schema) []by func cleanVersionMarkers(doc []byte) []byte { // Remove @since:vX.Y.Z patterns from the documentation result := reVersionPattern.ReplaceAll(doc, []byte("")) - // Clean up any extra spaces that might be left - result = regexp.MustCompile(`\s+`).ReplaceAll(result, []byte(" ")) + // Clean up any double spaces that might be left after removing @since markers + result = regexp.MustCompile(` +`).ReplaceAll(result, []byte(" ")) // Clean up trailing spaces at end of lines - result = regexp.MustCompile(` +\n`).ReplaceAll(result, []byte("\n")) + result = regexp.MustCompile(` +$`).ReplaceAllFunc(result, func(m []byte) []byte { + return []byte{} + }) return result } From e642c95364e21493aed2ace7c566409d8f641712 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:34:25 +0000 Subject: [PATCH 12/13] docs: update script.md after rebase Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- docs/resources/script.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/docs/resources/script.md b/docs/resources/script.md index 39b8808..a7236ea 100644 --- a/docs/resources/script.md +++ b/docs/resources/script.md @@ -22,7 +22,7 @@ resource "coder_agent" "dev" { } resource "coder_script" "dotfiles" { - agent_id = coder_agent.dev.agent_id + agent_id = coder_agent.dev.id display_name = "Dotfiles" icon = "/icon/dotfiles.svg" run_on_start = true @@ -33,7 +33,7 @@ resource "coder_script" "dotfiles" { } resource "coder_script" "code-server" { - agent_id = coder_agent.dev.agent_id + agent_id = coder_agent.dev.id display_name = "code-server" icon = "/icon/code.svg" run_on_start = true @@ -43,15 +43,26 @@ resource "coder_script" "code-server" { }) } -resource "coder_script" "nightly_sleep_reminder" { - agent_id = coder_agent.dev.agent_id +resource "coder_script" "nightly_update" { + agent_id = coder_agent.dev.id display_name = "Nightly update" icon = "/icon/database.svg" - cron = "0 22 * * *" + cron = "0 0 22 * * *" # Run at 22:00 (10 PM) every day script = <"`. - `log_path` (String) The path of a file to write the logs to. If relative, it will be appended to tmp. - `run_on_start` (Boolean) This option defines whether or not the script should run when the agent starts. The script should exit when it is done to signal that the agent is ready. From 83112e610911be59182b9a35ada165bfbba17c54 Mon Sep 17 00:00:00 2001 From: "blink-so[bot]" <211532188+blink-so[bot]@users.noreply.github.com> Date: Fri, 27 Jun 2025 18:42:00 +0000 Subject: [PATCH 13/13] docs: update VERSION_METADATA.md per review feedback - Update wording to be more specific about resources and data sources - Remove reference to deleted version_meta.go file - Clarify terraform-provider-coder v2.0 vs Coder v2.0 Co-authored-by: matifali <10648092+matifali@users.noreply.github.com> --- provider/VERSION_METADATA.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/provider/VERSION_METADATA.md b/provider/VERSION_METADATA.md index 3d5b396..f8de5a6 100644 --- a/provider/VERSION_METADATA.md +++ b/provider/VERSION_METADATA.md @@ -88,9 +88,9 @@ Results in documentation with: ## When to Add Version Information -- **Add @since: markers** for resources introduced after Coder v2.0 -- **Add @since: markers** for attributes added to existing resources -- **Don't add markers** for resources that existed before Coder v2.0 +- **Add @since: markers** for newly introduced resources and data sources +- **Add @since: markers** for attributes added to existing resources and data sources +- **Don't add markers** for resources that existed before terraform-provider-coder v2.0 - Resources and attributes without `@since:` markers won't show version information ## Best Practices @@ -99,7 +99,4 @@ Results in documentation with: 2. **Use semantic versioning** (vX.Y.Z format) 3. **Test documentation generation** with `make gen` after adding markers 4. **Keep descriptions concise** - the version marker is removed from the final docs -5. **Use the version constants** from `version_meta.go` when available: - ```go - Description: "My feature. @since:" + provider.V2_21_0, - ``` +