chore: update readme, add version warnings, examples

ethanndickson · ethanndickson · commit a052493e04c6 · 2024-08-13T05:38:28.000Z
diff --git a/README.md b/README.md
@@ -1,66 +1,33 @@
-# 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
 
-## 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 a test matrix against multiple Terraform versions.
diff --git 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
@@ -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 above.
 ---
 
 # 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 above.
 
 
 
diff --git 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
@@ -10,13 +10,7 @@ description: |-
 
 
 
-## Example Usage
 
-```terraform
-provider "coderd" {
-  # example configuration here
-}
-```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
diff --git a/examples/data-sources/coderd_example/data-source.tf b/examples/data-sources/coderd_example/data-source.tf
diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
diff --git a/examples/resources/coderd_example/resource.tf b/examples/resources/coderd_example/resource.tf
diff --git a/examples/resources/coderd_group/main.tf b/examples/resources/coderd_group/main.tf
@@ -0,0 +1,31 @@
+terraform {
+  required_providers {
+    coderd = {
+      source = "coder/coderd"
+    }
+  }
+}
+
+// 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/main.tf b/examples/resources/coderd_template/main.tf
@@ -0,0 +1,38 @@
+terraform {
+  required_providers {
+    coderd = {
+      source = "coder/coderd"
+    }
+  }
+}
+
+// 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/main.tf b/examples/resources/coderd_user/main.tf
@@ -0,0 +1,35 @@
+terraform {
+  required_providers {
+    coderd = {
+      source = "coder/coderd"
+    }
+  }
+}
+
+// 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
@@ -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
@@ -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 above.
+`,
 
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
diff --git 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{
