Skip to content

Commit ef286de

Browse files
ethanndicksonethanndickson
committed
docs: add examples for all resources & data sources
1 parent dfa7472 commit ef286de

File tree

19 files changed

+371
-17
lines changed

19 files changed

+371
-17
lines changed

‎docs/data-sources/group.md

+31
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,38 @@ description: |-
1010

1111
An existing group on the Coder deployment.
1212

13+
## Example Usage
1314

15+
```terraform
16+
// Get a group on the provider default organization by `id`
17+
data "coderd_group" "employees" {
18+
id = "abcd-efg-hijk"
19+
}
20+
21+
// Get a group on the provider default organization by `name` + `organization_id`
22+
data "coderd_group" "bosses" {
23+
name = "bosses"
24+
}
25+
26+
// Use them to apply ACL to a template
27+
resource "coderd_template" "example" {
28+
name = "example-template"
29+
versions = [/* ... */]
30+
acl = {
31+
groups = [
32+
{
33+
id = data.coderd_group.employees.id
34+
role = "use"
35+
},
36+
{
37+
id = data.coderd_group.bosses.id
38+
role = "admin"
39+
}
40+
]
41+
users = []
42+
}
43+
}
44+
```
1445

1546
<!-- schema generated by tfplugindocs -->
1647
## Schema

‎docs/data-sources/organization.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,29 @@ An existing organization on the Coder deployment.
1515
~> **Warning**
1616
This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
1717

18-
18+
## Example Usage
19+
20+
```terraform
21+
// Get the default (first) organization for the coder deployment
22+
data "coderd_organization" "default" {
23+
is_default = true
24+
}
25+
26+
// Get another organization by `id`
27+
data "coderd_organization" "example" {
28+
id = "abcd-efg-hijk"
29+
}
30+
31+
data "coderd_organization" "example2" {
32+
name = "example-organization-2"
33+
}
34+
35+
// Create a group on a specific organization
36+
resource "coderd_group" "example" {
37+
name = "example-group"
38+
organization_id = data.coderd_organization.default.id
39+
}
40+
```
1941

2042
<!-- schema generated by tfplugindocs -->
2143
## Schema

‎docs/data-sources/template.md

+13-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,19 @@ description: |-
1010

1111
An existing template on the Coder deployment.
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
// Get a template on the provider's default organization by `id`
17+
data "coderd_template" "example-template" {
18+
id = "abcd-efg-hijk"
19+
}
20+
21+
// Get a template on the provider's default organization by `name`
22+
data "coderd_template" "example-template2" {
23+
name = "example-template-2"
24+
}
25+
```
1426

1527
<!-- schema generated by tfplugindocs -->
1628
## Schema

‎docs/data-sources/user.md

+23-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,29 @@ description: |-
1010

1111
An existing user on the Coder deployment
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
// Get a user on the Coder deployment by `id`
17+
data "coderd_user" "manager" {
18+
id = "abcd-efg-hijk"
19+
}
20+
21+
// Get a user on the Coder deployment by `username`
22+
data "coderd_user" "admin" {
23+
username = "admin"
24+
}
25+
26+
27+
// Use them to create a group
28+
resource "coderd_group" "bosses" {
29+
name = "group"
30+
members = [
31+
data.coderd_user.admin.id,
32+
data.coderd_user.manager.id
33+
]
34+
}
35+
```
1436

1537
<!-- schema generated by tfplugindocs -->
1638
## Schema

‎docs/index.md

+68-2
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,88 @@
33
page_title: "coderd Provider"
44
subcategory: ""
55
description: |-
6+
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.
67
~> Warning
78
This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.10.1 and later.
89
---
910

1011
# coderd Provider
1112

13+
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.
14+
1215
~> **Warning**
1316
This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.10.1) and later.
1417

18+
## Example Usage
19+
20+
```terraform
21+
terraform {
22+
required_providers {
23+
coderd = {
24+
source = "coder/coderd"
25+
}
26+
}
27+
}
28+
29+
provider "coderd" {
30+
# `token` and `url` can be populated from environment variables.
31+
# `default_organization_id` can be populated using
32+
# the first organization the session token has access to.
33+
}
34+
35+
36+
data "coderd_organization" "default" {
37+
is_default = true
38+
}
39+
40+
data "coderd_user" "admin" {
41+
username = "admin"
42+
}
43+
44+
resource "coderd_user" "manager" {
45+
username = "Manager"
46+
email = "[email protected]"
47+
}
48+
49+
resource "coderd_group" "bosses" {
50+
name = "group"
51+
members = [
52+
data.coderd_user.admin.id,
53+
resource.coderd_user.manager.id
54+
]
55+
}
1556
57+
resource "coderd_template" "example" {
58+
name = "example-template"
59+
versions = [{
60+
directory = "./example-template"
61+
active = true
62+
tf_vars = [{
63+
name = "image_id"
64+
value = "ami-12345678"
65+
}]
66+
# Version names can be randomly generated if null/omitted
67+
}]
68+
acl = {
69+
groups = [{
70+
id = data.coderd_organization.default.id
71+
role = "use"
72+
},
73+
{
74+
id = resource.coderd_group.bosses.id
75+
role = "admin"
76+
}]
77+
users = []
78+
}
79+
allow_user_cancel_workspace_jobs = false
80+
}
81+
```
1682

1783
<!-- schema generated by tfplugindocs -->
1884
## Schema
1985

2086
### Optional
2187

2288
- `default_organization_id` (String) Default organization ID to use when creating resources. Defaults to the first organization the token has access to.
23-
- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to $CODER_SESSION_TOKEN.
24-
- `url` (String) URL to the Coder deployment. Defaults to $CODER_URL.
89+
- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`.
90+
- `url` (String) URL to the Coder deployment. Defaults to `$CODER_URL`.

‎docs/resources/group.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,15 @@
33
page_title: "coderd_group Resource - terraform-provider-coderd"
44
subcategory: ""
55
description: |-
6-
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.
6+
A group on the Coder deployment.
7+
To have a group resource with unmanaged members, but be able to read the members in Terraform, use the data.coderd_group data source. Creating groups requires an Enterprise license.
78
---
89

910
# coderd_group (Resource)
1011

11-
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.
12+
A group on the Coder deployment.
13+
14+
To have a group resource with unmanaged members, but be able to read the members in Terraform, use the `data.coderd_group` data source. Creating groups requires an Enterprise license.
1215

1316
## Example Usage
1417

‎docs/resources/template.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -55,23 +55,23 @@ resource "coderd_template" "ubuntu-main" {
5555

5656
### Optional
5757

58-
- `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))
58+
- `acl` (Attributes) (Enterprise) Access control list for the template. If null, ACL policies will not be added, removed, or inspected by Terraform. (see [below for nested schema](#nestedatt--acl))
5959
- `activity_bump_ms` (Number) The activity bump duration for all workspaces created from this template, in milliseconds. Defaults to one hour.
6060
- `allow_user_auto_start` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
6161
- `allow_user_auto_stop` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
6262
- `allow_user_cancel_workspace_jobs` (Boolean) Whether users can cancel in-progress workspace jobs using this template. Defaults to true.
6363
- `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.
6464
- `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))
6565
- `default_ttl_ms` (Number) The default time-to-live for all workspaces created from this template, in milliseconds.
66-
- `deprecation_message` (String) If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it.
66+
- `deprecation_message` (String) If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it. The provided message will be displayed.
6767
- `description` (String) A description of the template.
6868
- `display_name` (String) The display name of the template. Defaults to the template name.
6969
- `failure_ttl_ms` (Number) (Enterprise) The max lifetime before Coder stops all resources for failed workspaces created from this template, in milliseconds.
7070
- `icon` (String) Relative path or external URL that specifes an icon to be displayed in the dashboard.
7171
- `organization_id` (String) The ID of the organization. Defaults to the provider's default organization
7272
- `require_active_version` (Boolean) (Enterprise) Whether workspaces must be created from the active version of this template. Defaults to false.
7373
- `time_til_dormant_autodelete_ms` (Number) (Enterprise) The max lifetime before Coder permanently deletes dormant workspaces created from this template.
74-
- `time_til_dormant_ms` (Number) Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.
74+
- `time_til_dormant_ms` (Number) (Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.
7575

7676
### Read-Only
7777

‎docs/resources/user.md

+1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ resource "coderd_user" "audit" {
3939
resource "coderd_user" "admin" {
4040
username = "admin"
4141
suspended = true
42+
email = "[email protected]"
4243
}
4344
```
4445

‎docs/resources/workspace_proxy.md

+32-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,38 @@ description: |-
1010

1111
A Workspace Proxy for the Coder deployment.
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
resource "coderd_workspace_proxy" "sydney-wsp" {
17+
name = "sydney-wsp"
18+
display_name = "Australia (Sydney)"
19+
icon = "/emojis/1f1e6-1f1fa.png"
20+
}
21+
22+
resource "kubernetes_deployment" "syd_wsproxy" {
23+
metadata { /* ... */ }
24+
spec {
25+
template {
26+
metadata { /* ... */ }
27+
spec {
28+
container {
29+
name = "syd-wsp"
30+
image = "ghcr.io/coder/coder:latest"
31+
args = ["wsproxy"]
32+
env {
33+
name = "CODER_PROXY_SESSION_TOKEN"
34+
value = coderd_workspace_proxy.sydney-wsp.session_token
35+
}
36+
/* ... */
37+
}
38+
/* ... */
39+
}
40+
}
41+
/* ... */
42+
}
43+
}
44+
```
1445

1546
<!-- schema generated by tfplugindocs -->
1647
## Schema

‎examples/data-sources/coderd_group/data-source.tf

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// Get a group on the provider default organization by `id`
2+
data "coderd_group" "employees" {
3+
id = "abcd-efg-hijk"
4+
}
5+
6+
// Get a group on the provider default organization by `name` + `organization_id`
7+
data "coderd_group" "bosses" {
8+
name = "bosses"
9+
}
10+
11+
// Use them to apply ACL to a template
12+
resource "coderd_template" "example" {
13+
name = "example-template"
14+
versions = [/* ... */]
15+
acl = {
16+
groups = [
17+
{
18+
id = data.coderd_group.employees.id
19+
role = "use"
20+
},
21+
{
22+
id = data.coderd_group.bosses.id
23+
role = "admin"
24+
}
25+
]
26+
users = []
27+
}
28+
}

‎examples/data-sources/coderd_organization/data-source.tf

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Get the default (first) organization for the coder deployment
2+
data "coderd_organization" "default" {
3+
is_default = true
4+
}
5+
6+
// Get another organization by `id`
7+
data "coderd_organization" "example" {
8+
id = "abcd-efg-hijk"
9+
}
10+
11+
data "coderd_organization" "example2" {
12+
name = "example-organization-2"
13+
}
14+
15+
// Create a group on a specific organization
16+
resource "coderd_group" "example" {
17+
name = "example-group"
18+
organization_id = data.coderd_organization.default.id
19+
}

‎examples/data-sources/coderd_template/data-source.tf

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Get a template on the provider's default organization by `id`
2+
data "coderd_template" "example-template" {
3+
id = "abcd-efg-hijk"
4+
}
5+
6+
// Get a template on the provider's default organization by `name`
7+
data "coderd_template" "example-template2" {
8+
name = "example-template-2"
9+
}

‎examples/data-sources/coderd_user/data-source.tf

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Get a user on the Coder deployment by `id`
2+
data "coderd_user" "manager" {
3+
id = "abcd-efg-hijk"
4+
}
5+
6+
// Get a user on the Coder deployment by `username`
7+
data "coderd_user" "admin" {
8+
username = "admin"
9+
}
10+
11+
12+
// Use them to create a group
13+
resource "coderd_group" "bosses" {
14+
name = "group"
15+
members = [
16+
data.coderd_user.admin.id,
17+
data.coderd_user.manager.id
18+
]
19+
}

0 commit comments

Comments
 (0)