chore: update readme, add version warnings, examples

README.md

@@ -1,66 +1,35 @@
-# 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
 
 If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
 
 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.

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.
 
 
 

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.
 
 
 

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
 
 
 

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

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    = "[email protected]"
+}
+
+resource "coderd_user" "coder2" {
+  username = "coder2"
+  name     = "Coder One"
+  email    = "[email protected]"
+}
+
+// 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

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    = "[email protected]"
+}
+
+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

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      = "[email protected]"
+  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      = "[email protected]"
+  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

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    = "[email protected]"
+}
+
+resource "coderd_user" "coder2" {
+  username = "coder2"
+  name     = "Coder One"
+  email    = "[email protected]"
+}
+
+// Add two users to the group by their ID.
+resource "coderd_group" "group1" {
+  name = "group1"
+  members = [
+    coderd_user.coder1.id,
+    coderd_user.coder2.id
+  ]
+}

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    = "[email protected]"
+}
+
+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"
+    }
+  ]
+}

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      = "[email protected]"
+  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      = "[email protected]"
+  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
+}

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{