docs: add examples for all resources & data sources (#78)

Author: ethanndickson

Diff for: docs/data-sources/group.md

@@ -10,7 +10,38 @@ description: |-
 
 An existing group on the Coder deployment.
 
+## Example Usage
 
+```terraform
+// Get a group on the provider default organization by `id`
+data "coderd_group" "employees" {
+  id = "abcd-efg-hijk"
+}
+
+// Get a group on the provider default organization by `name` + `organization_id`
+data "coderd_group" "bosses" {
+  name = "bosses"
+}
+
+// Use them to apply ACL to a template
+resource "coderd_template" "example" {
+  name     = "example-template"
+  versions = [/* ... */]
+  acl = {
+    groups = [
+      {
+        id   = data.coderd_group.employees.id
+        role = "use"
+      },
+      {
+        id   = data.coderd_group.bosses.id
+        role = "admin"
+      }
+    ]
+    users = []
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

Diff for: docs/data-sources/organization.md

@@ -15,7 +15,30 @@ 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.
 
-
+## Example Usage
+
+```terraform
+// Get the default (first) organization for the coder deployment
+data "coderd_organization" "default" {
+  is_default = true
+}
+
+// Get another organization by `id`
+data "coderd_organization" "example" {
+  id = "abcd-efg-hijk"
+}
+
+// Or get by name
+data "coderd_organization" "example2" {
+  name = "example-organization-2"
+}
+
+// Create a group on a specific organization
+resource "coderd_group" "example" {
+  name            = "example-group"
+  organization_id = data.coderd_organization.example.id
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

Diff for: docs/data-sources/template.md

@@ -10,7 +10,31 @@ description: |-
 
 An existing template on the Coder deployment.
 
+## Example Usage
 
+```terraform
+// Get a template on the provider's default organization by `id`
+data "coderd_template" "ubuntu-main" {
+  id = "abcd-efg-hijk"
+}
+
+// Get a template on the provider's default organization by `name`
+data "coderd_template" "windows-main" {
+  name = "windows-main"
+}
+
+// Manage a template resource with the same permissions & settings as an existing template
+resource "coderd_template" "debian-main" {
+  name                              = "debian-main"
+  versions                          = [/* ... */]
+  acl                               = data.coderd_template.ubuntu-main.acl
+  allow_user_auto_start             = data.coderd_template.ubuntu-main.allow_user_auto_start
+  auto_start_permitted_days_of_week = data.coderd_template.ubuntu-main.auto_start_permitted_days_of_week
+  allow_user_auto_stop              = data.coderd_template.ubuntu-main.allow_user_auto_stop
+  auto_stop_requirement             = data.coderd_template.ubuntu-main.auto_stop_requirement
+  allow_user_cancel_workspace_jobs  = data.coderd_template.ubuntu-main.allow_user_cancel_workspace_jobs
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

Diff for: docs/data-sources/user.md

@@ -10,7 +10,29 @@ description: |-
 
 An existing user on the Coder deployment
 
-
+## Example Usage
+
+```terraform
+// Get a user on the Coder deployment by `id`
+data "coderd_user" "manager" {
+  id = "abcd-efg-hijk"
+}
+
+// Get a user on the Coder deployment by `username`
+data "coderd_user" "admin" {
+  username = "admin"
+}
+
+
+// Use them to create a group
+resource "coderd_group" "bosses" {
+  name = "group"
+  members = [
+    data.coderd_user.admin.id,
+    data.coderd_user.manager.id
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

Diff for: docs/index.md

@@ -3,22 +3,87 @@
 page_title: "coderd Provider"
 subcategory: ""
 description: |-
+  The coderd provider can be used to manage resources on a Coder deployment. The provider exposes resources and data sources for users, groups, templates, and workspace proxies.
   ~> Warning
   This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.10.1 and later.
 ---
 
 # coderd Provider
 
+The coderd provider can be used to manage resources on a Coder deployment. The provider exposes resources and data sources for users, groups, templates, and workspace proxies.
+
 ~> **Warning**
 This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.10.1) and later.
 
+## Example Usage
+
+```terraform
+terraform {
+  required_providers {
+    coderd = {
+      source = "coder/coderd"
+    }
+  }
+}
+
+provider "coderd" {
+  url   = "coder.example.com"
+  token = "****"
+}
+
+
+data "coderd_organization" "default" {
+  is_default = true
+}
+
+data "coderd_user" "admin" {
+  username = "admin"
+}
+
+resource "coderd_user" "manager" {
+  username = "Manager"
+  email    = "[email protected]"
+}
+
+resource "coderd_group" "bosses" {
+  name = "group"
+  members = [
+    data.coderd_user.admin.id,
+    resource.coderd_user.manager.id
+  ]
+}
 
+resource "coderd_template" "example" {
+  name = "example-template"
+  versions = [{
+    directory = "./example-template"
+    active    = true
+    tf_vars = [{
+      name  = "image_id"
+      value = "ami-12345678"
+    }]
+    # Version names can be randomly generated if null/omitted
+  }]
+  acl = {
+    groups = [{
+      id   = data.coderd_organization.default.id
+      role = "use"
+      },
+      {
+        id   = resource.coderd_group.bosses.id
+        role = "admin"
+    }]
+    users = []
+  }
+  allow_user_cancel_workspace_jobs = false
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
 - `default_organization_id` (String) Default organization ID to use when creating resources. Defaults to the first organization the token has access to.
-- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to $CODER_SESSION_TOKEN.
-- `url` (String) URL to the Coder deployment. Defaults to $CODER_URL.
+- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`.
+- `url` (String) URL to the Coder deployment. Defaults to `$CODER_URL`.

Diff for: docs/resources/group.md

@@ -3,12 +3,15 @@
 page_title: "coderd_group Resource - terraform-provider-coderd"
 subcategory: ""
 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.
+  A group on the Coder deployment.
+  Creating groups requires an Enterprise license.
 ---
 
 # coderd_group (Resource)
 
-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.
+A group on the Coder deployment.
+
+Creating groups requires an Enterprise license.
 
 ## Example Usage
 
@@ -49,7 +52,7 @@ resource "coderd_group" "group1" {
 
 - `avatar_url` (String) The URL of the group's avatar.
 - `display_name` (String) The display name of the group. Defaults to the group name.
-- `members` (Set of String) Members of the group, by ID. If null, members will not be added or removed by Terraform.
+- `members` (Set of String) Members of the group, by ID. If null, members will not be added or removed by Terraform. To have a group resource with unmanaged members, but be able to read the members in Terraform, use `data.coderd_group`
 - `organization_id` (String) The organization ID that the group belongs to. Defaults to the provider default organization ID.
 - `quota_allowance` (Number) The number of quota credits to allocate to each user in the group.
 

Diff for: docs/resources/template.md

@@ -42,6 +42,12 @@ resource "coderd_template" "ubuntu-main" {
       directory   = "./staging-template"
     }
   ]
+  acl = {
+    users = [{
+      id   = coderd_user.coder1.id
+      role = "admin"
+    }]
+  }
 }
 ```
 
@@ -55,23 +61,23 @@ resource "coderd_template" "ubuntu-main" {
 
 ### Optional
 
-- `acl` (Attributes) (Enterprise) Access control list for the template. If null, ACL policies will not be added or removed by Terraform. (see [below for nested schema](#nestedatt--acl))
+- `acl` (Attributes) (Enterprise) Access control list for the template. If null, ACL policies will not be added, removed, or read by Terraform. (see [below for nested schema](#nestedatt--acl))
 - `activity_bump_ms` (Number) The activity bump duration for all workspaces created from this template, in milliseconds. Defaults to one hour.
 - `allow_user_auto_start` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
 - `allow_user_auto_stop` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
 - `allow_user_cancel_workspace_jobs` (Boolean) Whether users can cancel in-progress workspace jobs using this template. Defaults to true.
 - `auto_start_permitted_days_of_week` (Set of String) (Enterprise) List of days of the week in which autostart is allowed to happen, for all workspaces created from this template. Defaults to all days. If no days are specified, autostart is not allowed.
 - `auto_stop_requirement` (Attributes) (Enterprise) The auto-stop requirement for all workspaces created from this template. (see [below for nested schema](#nestedatt--auto_stop_requirement))
 - `default_ttl_ms` (Number) The default time-to-live for all workspaces created from this template, in milliseconds.
-- `deprecation_message` (String) If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it.
+- `deprecation_message` (String) If set, the template will be marked as deprecated with the provided message and users will be blocked from creating new workspaces from it.
 - `description` (String) A description of the template.
 - `display_name` (String) The display name of the template. Defaults to the template name.
 - `failure_ttl_ms` (Number) (Enterprise) The max lifetime before Coder stops all resources for failed workspaces created from this template, in milliseconds.
 - `icon` (String) Relative path or external URL that specifes an icon to be displayed in the dashboard.
 - `organization_id` (String) The ID of the organization. Defaults to the provider's default organization
 - `require_active_version` (Boolean) (Enterprise) Whether workspaces must be created from the active version of this template. Defaults to false.
 - `time_til_dormant_autodelete_ms` (Number) (Enterprise) The max lifetime before Coder permanently deletes dormant workspaces created from this template.
-- `time_til_dormant_ms` (Number) Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.
+- `time_til_dormant_ms` (Number) (Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.
 
 ### Read-Only
 

Diff for: docs/resources/user.md

@@ -39,6 +39,7 @@ resource "coderd_user" "audit" {
 resource "coderd_user" "admin" {
   username  = "admin"
   suspended = true
+  email     = "[email protected]"
 }
 ```
 

Diff for: docs/resources/workspace_proxy.md

@@ -10,7 +10,38 @@ description: |-
 
 A Workspace Proxy for the Coder deployment.
 
-
+## Example Usage
+
+```terraform
+resource "coderd_workspace_proxy" "sydney-wsp" {
+  name         = "sydney-wsp"
+  display_name = "Australia (Sydney)"
+  icon         = "/emojis/1f1e6-1f1fa.png"
+}
+
+resource "kubernetes_deployment" "syd_wsproxy" {
+  metadata { /* ... */ }
+  spec {
+    template {
+      metadata { /* ... */ }
+      spec {
+        container {
+          name  = "syd-wsp"
+          image = "ghcr.io/coder/coder:latest"
+          args  = ["wsproxy", "server"]
+          env {
+            name  = "CODER_PROXY_SESSION_TOKEN"
+            value = coderd_workspace_proxy.sydney-wsp.session_token
+          }
+          /* ... */
+        }
+        /* ... */
+      }
+    }
+    /* ... */
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

Diff for: examples/data-sources/coderd_group/data-source.tf

@@ -0,0 +1,28 @@
+// Get a group on the provider default organization by `id`
+data "coderd_group" "employees" {
+  id = "abcd-efg-hijk"
+}
+
+// Get a group on the provider default organization by `name` + `organization_id`
+data "coderd_group" "bosses" {
+  name = "bosses"
+}
+
+// Use them to apply ACL to a template
+resource "coderd_template" "example" {
+  name     = "example-template"
+  versions = [/* ... */]
+  acl = {
+    groups = [
+      {
+        id   = data.coderd_group.employees.id
+        role = "use"
+      },
+      {
+        id   = data.coderd_group.bosses.id
+        role = "admin"
+      }
+    ]
+    users = []
+  }
+}

Diff for: examples/data-sources/coderd_organization/data-source.tf

@@ -0,0 +1,20 @@
+// Get the default (first) organization for the coder deployment
+data "coderd_organization" "default" {
+  is_default = true
+}
+
+// Get another organization by `id`
+data "coderd_organization" "example" {
+  id = "abcd-efg-hijk"
+}
+
+// Or get by name
+data "coderd_organization" "example2" {
+  name = "example-organization-2"
+}
+
+// Create a group on a specific organization
+resource "coderd_group" "example" {
+  name            = "example-group"
+  organization_id = data.coderd_organization.example.id
+}