diff --git a/README.md b/README.md
index e11186c..8eeafa0 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,23 @@
-# Coderd Terraform Provider
+# terraform-provider-coderd
-# ⚠️ WORK IN PROGRESS - DO NOT USE ⚠️
+`terraform-provider-coderd` enables managing a [Coder](https://github.com/coder/coder) deployment using [Terraform](https://github.com/hashicorp/terraform) IaC.
-_This template repository is built on the [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). The template repository built on the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) can be found at [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding). See [Which SDK Should I Use?](https://developer.hashicorp.com/terraform/plugin/framework-benefits) in the Terraform documentation for additional information._
-
-This repository is a *template* for a [Terraform](https://www.terraform.io) provider. It is intended as a starting point for creating Terraform providers, containing:
-
-- A resource and a data source (`internal/provider/`),
-- Examples (`examples/`) and generated documentation (`docs/`),
-- Miscellaneous meta files.
-
-These files contain boilerplate code that you will need to edit to create your own Terraform provider. Tutorials for creating Terraform providers can be found on the [HashiCorp Developer](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework) platform. _Terraform Plugin Framework specific guides are titled accordingly._
-
-Please see the [GitHub template repository documentation](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) for how to create a new repository from this template on GitHub.
-
-Once you've written your provider, you'll want to [publish it on the Terraform Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing) so that others can use it.
+The provider currently supports resources and data sources for:
+- Users
+- Templates + Template Versions
+- Groups
+- Workspace Proxies
+- Organizations (Data Source only)
## Requirements
- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
- [Go](https://golang.org/doc/install) >= 1.21
+- [Coder](https://github.com/coder/coder) >= 2.10.1
-## Building The Provider
-
-1. Clone the repository
-1. Enter the repository directory
-1. Build the provider using the Go `install` command:
-
-```shell
-go install
-```
-
-## Adding Dependencies
-
-This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
-Please see the Go documentation for the most up to date information about using Go modules.
-
-To add a new dependency `github.com/author/dependency` to your Terraform provider:
-
-```shell
-go get github.com/author/dependency
-go mod tidy
-```
-
-Then commit the changes to `go.mod` and `go.sum`.
-
-## Using the provider
+## Usage
-Fill this in for each provider
+See the [`examples`](examples) and the [documentation](https://registry.terraform.io/providers/coder/coderd/latest/docs).
## Developing the Provider
@@ -55,12 +25,11 @@ If you wish to work on the provider, you'll first need [Go](http://www.golang.or
To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
-To generate or update documentation, run `go generate`.
+To generate or update documentation, run `make gen`.
-In order to run the full suite of Acceptance tests, run `make testacc`.
+### Terraform Acceptance Tests
-*Note:* Acceptance tests create real resources, and often cost money to run.
+Acceptance tests are run against a live Coder deployment in a local Docker container. To run the full suite of Acceptance tests, run `make testacc`.
-```shell
-make testacc
-```
+> [!NOTE]
+> Our [CI workflow](./github/workflows/test.yml) runs an acceptance test matrix against multiple Terraform versions.
diff --git a/docs/data-sources/group.md b/docs/data-sources/group.md
index eb790f5..37d3f7a 100644
--- a/docs/data-sources/group.md
+++ b/docs/data-sources/group.md
@@ -3,12 +3,12 @@
page_title: "coderd_group Data Source - terraform-provider-coderd"
subcategory: ""
description: |-
- An existing group on the coder deployment.
+ An existing group on the Coder deployment.
---
# coderd_group (Data Source)
-An existing group on the coder deployment.
+An existing group on the Coder deployment.
diff --git a/docs/data-sources/organization.md b/docs/data-sources/organization.md
index f1fcac6..26b8cdd 100644
--- a/docs/data-sources/organization.md
+++ b/docs/data-sources/organization.md
@@ -3,12 +3,17 @@
page_title: "coderd_organization Data Source - terraform-provider-coderd"
subcategory: ""
description: |-
- An existing organization on the coder deployment.
+ An existing organization on the Coder deployment.
+ ~> Warning
+ This data source is only compatible with Coder version 2.13.0 https://github.com/coder/coder/releases/tag/v2.13.0 and later.
---
# coderd_organization (Data Source)
-An existing organization on the coder deployment.
+An existing organization on the Coder deployment.
+
+~> **Warning**
+This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md
index b7b21db..35557e7 100644
--- a/docs/data-sources/user.md
+++ b/docs/data-sources/user.md
@@ -3,12 +3,12 @@
page_title: "coderd_user Data Source - terraform-provider-coderd"
subcategory: ""
description: |-
- An existing user on the coder deployment
+ An existing user on the Coder deployment
---
# coderd_user (Data Source)
-An existing user on the coder deployment
+An existing user on the Coder deployment
diff --git a/docs/index.md b/docs/index.md
index 974962c..d373b16 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,20 +3,16 @@
page_title: "coderd Provider"
subcategory: ""
description: |-
-
+ ~> Warning
+ This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.13.0 and later.
---
# coderd Provider
+~> **Warning**
+This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
-## Example Usage
-
-```terraform
-provider "coderd" {
- # example configuration here
-}
-```
<!-- schema generated by tfplugindocs -->
## Schema
diff --git a/docs/resources/group.md b/docs/resources/group.md
index ec10901..3e7220a 100644
--- a/docs/resources/group.md
+++ b/docs/resources/group.md
@@ -10,7 +10,33 @@ description: |-
A group on the Coder deployment. If you want to have a group resource with unmanaged members, but still want to read the members in Terraform, use the `data.coderd_group` data source. Creating groups requires an Enterprise license.
-
+## Example Usage
+
+```terraform
+// Provider populated from environment variables
+provider "coderd" {}
+
+resource "coderd_user" "coder1" {
+ username = "coder1"
+ name = "Coder One"
+ email = "coder1@coder.com"
+}
+
+resource "coderd_user" "coder2" {
+ username = "coder2"
+ name = "Coder One"
+ email = "coder2@coder.com"
+}
+
+// Add two users to the group by their ID.
+resource "coderd_group" "group1" {
+ name = "group1"
+ members = [
+ coderd_user.coder1.id,
+ coderd_user.coder2.id
+ ]
+}
+```
<!-- schema generated by tfplugindocs -->
## Schema
diff --git a/docs/resources/template.md b/docs/resources/template.md
index 598f385..185e52e 100644
--- a/docs/resources/template.md
+++ b/docs/resources/template.md
@@ -10,7 +10,40 @@ description: |-
A Coder template
-
+## Example Usage
+
+```terraform
+// Provider populated from environment variables
+provider "coderd" {}
+
+// Get the commit SHA of the configuration's git repository
+variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" {
+ type = string
+}
+
+resource "coderd_user" "coder1" {
+ username = "coder1"
+ name = "Coder One"
+ email = "coder1@coder.com"
+}
+
+resource "coderd_template" "ubuntu-main" {
+ name = "ubuntu-main"
+ description = "The main template for developing on Ubuntu."
+ versions = [
+ {
+ name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
+ description = "The stable version of the template."
+ directory = "./stable-template"
+ },
+ {
+ name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
+ description = "The staging version of the template."
+ directory = "./staging-template"
+ }
+ ]
+}
+```
<!-- schema generated by tfplugindocs -->
## Schema
diff --git a/docs/resources/user.md b/docs/resources/user.md
index 5672928..dd54af7 100644
--- a/docs/resources/user.md
+++ b/docs/resources/user.md
@@ -10,7 +10,37 @@ description: |-
A user on the Coder deployment.
-
+## Example Usage
+
+```terraform
+// Provider populated from environemnt variables
+provider "coderd" {}
+
+// Create a bot user for Jenkins
+resource "coderd_user" "jenkins" {
+ username = "jenkins"
+ name = "Jenkins CI/CD"
+ email = "ci@example.com"
+ roles = ["template-admin"]
+ login_type = "none"
+}
+
+// Keep the password of a user account up to date from an external source
+resource "coderd_user" "audit" {
+ username = "auditor"
+ name = "Auditor"
+ email = "security@example.com"
+ roles = ["auditor"]
+ login_type = "password"
+ password = data.vault_password.auditor.value
+}
+
+// Ensure the admin account is suspended
+resource "coderd_user" "admin" {
+ username = "admin"
+ suspended = true
+}
+```
<!-- schema generated by tfplugindocs -->
## Schema
diff --git a/examples/README.md b/examples/README.md
deleted file mode 100644
index 026c42c..0000000
--- a/examples/README.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Examples
-
-This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI.
-
-The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation.
-
-* **provider/provider.tf** example file for the provider index page
-* **data-sources/`full data source name`/data-source.tf** example file for the named data source page
-* **resources/`full resource name`/resource.tf** example file for the named data source page
diff --git a/examples/data-sources/coderd_example/data-source.tf b/examples/data-sources/coderd_example/data-source.tf
deleted file mode 100644
index db00893..0000000
--- a/examples/data-sources/coderd_example/data-source.tf
+++ /dev/null
@@ -1,3 +0,0 @@
-data "coderd_example" "example" {
- configurable_attribute = "some-value"
-}
diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
deleted file mode 100644
index 8d3fb0e..0000000
--- a/examples/provider/provider.tf
+++ /dev/null
@@ -1,3 +0,0 @@
-provider "coderd" {
- # example configuration here
-}
diff --git a/examples/resources/coderd_example/resource.tf b/examples/resources/coderd_example/resource.tf
deleted file mode 100644
index ccfd842..0000000
--- a/examples/resources/coderd_example/resource.tf
+++ /dev/null
@@ -1,3 +0,0 @@
-resource "coderd_example" "example" {
- configurable_attribute = "some-value"
-}
diff --git a/examples/resources/coderd_group/resource.tf b/examples/resources/coderd_group/resource.tf
new file mode 100644
index 0000000..0909dc0
--- /dev/null
+++ b/examples/resources/coderd_group/resource.tf
@@ -0,0 +1,23 @@
+// Provider populated from environment variables
+provider "coderd" {}
+
+resource "coderd_user" "coder1" {
+ username = "coder1"
+ name = "Coder One"
+ email = "coder1@coder.com"
+}
+
+resource "coderd_user" "coder2" {
+ username = "coder2"
+ name = "Coder One"
+ email = "coder2@coder.com"
+}
+
+// Add two users to the group by their ID.
+resource "coderd_group" "group1" {
+ name = "group1"
+ members = [
+ coderd_user.coder1.id,
+ coderd_user.coder2.id
+ ]
+}
diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf
new file mode 100644
index 0000000..b95f23d
--- /dev/null
+++ b/examples/resources/coderd_template/resource.tf
@@ -0,0 +1,30 @@
+// Provider populated from environment variables
+provider "coderd" {}
+
+// Get the commit SHA of the configuration's git repository
+variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" {
+ type = string
+}
+
+resource "coderd_user" "coder1" {
+ username = "coder1"
+ name = "Coder One"
+ email = "coder1@coder.com"
+}
+
+resource "coderd_template" "ubuntu-main" {
+ name = "ubuntu-main"
+ description = "The main template for developing on Ubuntu."
+ versions = [
+ {
+ name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
+ description = "The stable version of the template."
+ directory = "./stable-template"
+ },
+ {
+ name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
+ description = "The staging version of the template."
+ directory = "./staging-template"
+ }
+ ]
+}
diff --git a/examples/resources/coderd_user/resource.tf b/examples/resources/coderd_user/resource.tf
new file mode 100644
index 0000000..ed6e380
--- /dev/null
+++ b/examples/resources/coderd_user/resource.tf
@@ -0,0 +1,27 @@
+// Provider populated from environemnt variables
+provider "coderd" {}
+
+// Create a bot user for Jenkins
+resource "coderd_user" "jenkins" {
+ username = "jenkins"
+ name = "Jenkins CI/CD"
+ email = "ci@example.com"
+ roles = ["template-admin"]
+ login_type = "none"
+}
+
+// Keep the password of a user account up to date from an external source
+resource "coderd_user" "audit" {
+ username = "auditor"
+ name = "Auditor"
+ email = "security@example.com"
+ roles = ["auditor"]
+ login_type = "password"
+ password = data.vault_password.auditor.value
+}
+
+// Ensure the admin account is suspended
+resource "coderd_user" "admin" {
+ username = "admin"
+ suspended = true
+}
diff --git a/internal/provider/group_data_source.go b/internal/provider/group_data_source.go
index 5af8998..95c8e6e 100644
--- a/internal/provider/group_data_source.go
+++ b/internal/provider/group_data_source.go
@@ -56,7 +56,7 @@ func (d *GroupDataSource) Metadata(ctx context.Context, req datasource.MetadataR
func (d *GroupDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{
- MarkdownDescription: "An existing group on the coder deployment.",
+ MarkdownDescription: "An existing group on the Coder deployment.",
Attributes: map[string]schema.Attribute{
"id": schema.StringAttribute{
diff --git a/internal/provider/organization_data_source.go b/internal/provider/organization_data_source.go
index 8471adc..59b598c 100644
--- a/internal/provider/organization_data_source.go
+++ b/internal/provider/organization_data_source.go
@@ -46,7 +46,11 @@ func (d *OrganizationDataSource) Metadata(ctx context.Context, req datasource.Me
func (d *OrganizationDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{
- MarkdownDescription: "An existing organization on the coder deployment.",
+ MarkdownDescription: `An existing organization on the Coder deployment.
+
+~> **Warning**
+This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
+`,
Attributes: map[string]schema.Attribute{
"id": schema.StringAttribute{
diff --git a/internal/provider/provider.go b/internal/provider/provider.go
index 456adb3..34272a9 100644
--- a/internal/provider/provider.go
+++ b/internal/provider/provider.go
@@ -52,6 +52,10 @@ func (p *CoderdProvider) Metadata(ctx context.Context, req provider.MetadataRequ
func (p *CoderdProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
resp.Schema = schema.Schema{
+ MarkdownDescription: `
+~> **Warning**
+This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
+`,
Attributes: map[string]schema.Attribute{
"url": schema.StringAttribute{
MarkdownDescription: "URL to the Coder deployment. Defaults to $CODER_URL.",
diff --git a/internal/provider/user_data_source.go b/internal/provider/user_data_source.go
index c1675a3..7c5846f 100644
--- a/internal/provider/user_data_source.go
+++ b/internal/provider/user_data_source.go
@@ -50,7 +50,7 @@ func (d *UserDataSource) Metadata(ctx context.Context, req datasource.MetadataRe
func (d *UserDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
resp.Schema = schema.Schema{
- MarkdownDescription: "An existing user on the coder deployment",
+ MarkdownDescription: "An existing user on the Coder deployment",
// Validation handled by ConfigValidators
Attributes: map[string]schema.Attribute{