Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 6ebd419

Browse files
ethanndicksonethanndickson
committedAug 22, 2024·
docs: add examples for all resources & data sources
1 parent dfa7472 commit 6ebd419

File tree

20 files changed

+385
-19
lines changed

20 files changed

+385
-19
lines changed
 

‎docs/data-sources/group.md

Lines changed: 31 additions & 0 deletions
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

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,30 @@ 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+
// Or get by name
32+
data "coderd_organization" "example2" {
33+
name = "example-organization-2"
34+
}
35+
36+
// Create a group on a specific organization
37+
resource "coderd_group" "example" {
38+
name = "example-group"
39+
organization_id = data.coderd_organization.default.id
40+
}
41+
```
1942

2043
<!-- schema generated by tfplugindocs -->
2144
## Schema

‎docs/data-sources/template.md

Lines changed: 13 additions & 1 deletion
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

Lines changed: 23 additions & 1 deletion
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

Lines changed: 67 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,87 @@
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+
url = "coder.example.com"
31+
token = "****"
32+
}
33+
34+
35+
data "coderd_organization" "default" {
36+
is_default = true
37+
}
38+
39+
data "coderd_user" "admin" {
40+
username = "admin"
41+
}
42+
43+
resource "coderd_user" "manager" {
44+
username = "Manager"
45+
email = "manager@example.com"
46+
}
47+
48+
resource "coderd_group" "bosses" {
49+
name = "group"
50+
members = [
51+
data.coderd_user.admin.id,
52+
resource.coderd_user.manager.id
53+
]
54+
}
1555
56+
resource "coderd_template" "example" {
57+
name = "example-template"
58+
versions = [{
59+
directory = "./example-template"
60+
active = true
61+
tf_vars = [{
62+
name = "image_id"
63+
value = "ami-12345678"
64+
}]
65+
# Version names can be randomly generated if null/omitted
66+
}]
67+
acl = {
68+
groups = [{
69+
id = data.coderd_organization.default.id
70+
role = "use"
71+
},
72+
{
73+
id = resource.coderd_group.bosses.id
74+
role = "admin"
75+
}]
76+
users = []
77+
}
78+
allow_user_cancel_workspace_jobs = false
79+
}
80+
```
1681

1782
<!-- schema generated by tfplugindocs -->
1883
## Schema
1984

2085
### Optional
2186

2287
- `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.
88+
- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`.
89+
- `url` (String) URL to the Coder deployment. Defaults to `$CODER_URL`.

‎docs/resources/group.md

Lines changed: 6 additions & 3 deletions
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+
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+
Creating groups requires an Enterprise license.
1215

1316
## Example Usage
1417

@@ -49,7 +52,7 @@ resource "coderd_group" "group1" {
4952

5053
- `avatar_url` (String) The URL of the group's avatar.
5154
- `display_name` (String) The display name of the group. Defaults to the group name.
52-
- `members` (Set of String) Members of the group, by ID. If null, members will not be added or removed by Terraform.
55+
- `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`
5356
- `organization_id` (String) The organization ID that the group belongs to. Defaults to the provider default organization ID.
5457
- `quota_allowance` (Number) The number of quota credits to allocate to each user in the group.
5558

‎docs/resources/template.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ resource "coderd_template" "ubuntu-main" {
4242
directory = "./staging-template"
4343
}
4444
]
45+
acl = {
46+
users = [{
47+
id = coderd_user.coder1.id
48+
role = "admin"
49+
}]
50+
}
4551
}
4652
```
4753

@@ -55,23 +61,23 @@ resource "coderd_template" "ubuntu-main" {
5561

5662
### Optional
5763

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))
64+
- `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))
5965
- `activity_bump_ms` (Number) The activity bump duration for all workspaces created from this template, in milliseconds. Defaults to one hour.
6066
- `allow_user_auto_start` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
6167
- `allow_user_auto_stop` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true.
6268
- `allow_user_cancel_workspace_jobs` (Boolean) Whether users can cancel in-progress workspace jobs using this template. Defaults to true.
6369
- `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.
6470
- `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))
6571
- `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.
72+
- `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.
6773
- `description` (String) A description of the template.
6874
- `display_name` (String) The display name of the template. Defaults to the template name.
6975
- `failure_ttl_ms` (Number) (Enterprise) The max lifetime before Coder stops all resources for failed workspaces created from this template, in milliseconds.
7076
- `icon` (String) Relative path or external URL that specifes an icon to be displayed in the dashboard.
7177
- `organization_id` (String) The ID of the organization. Defaults to the provider's default organization
7278
- `require_active_version` (Boolean) (Enterprise) Whether workspaces must be created from the active version of this template. Defaults to false.
7379
- `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.
80+
- `time_til_dormant_ms` (Number) (Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.
7581

7682
### Read-Only
7783

‎docs/resources/user.md

Lines changed: 1 addition & 0 deletions
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 = "admin@example.com"
4243
}
4344
```
4445

‎docs/resources/workspace_proxy.md

Lines changed: 32 additions & 1 deletion
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", "server"]
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

Lines changed: 28 additions & 0 deletions
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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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+
// Or get by name
12+
data "coderd_organization" "example2" {
13+
name = "example-organization-2"
14+
}
15+
16+
// Create a group on a specific organization
17+
resource "coderd_group" "example" {
18+
name = "example-group"
19+
organization_id = data.coderd_organization.default.id
20+
}

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

Lines changed: 9 additions & 0 deletions
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

Lines changed: 19 additions & 0 deletions
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+
}

‎examples/provider/provider.tf

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
terraform {
2+
required_providers {
3+
coderd = {
4+
source = "coder/coderd"
5+
}
6+
}
7+
}
8+
9+
provider "coderd" {
10+
url = "coder.example.com"
11+
token = "****"
12+
}
13+
14+
15+
data "coderd_organization" "default" {
16+
is_default = true
17+
}
18+
19+
data "coderd_user" "admin" {
20+
username = "admin"
21+
}
22+
23+
resource "coderd_user" "manager" {
24+
username = "Manager"
25+
email = "manager@example.com"
26+
}
27+
28+
resource "coderd_group" "bosses" {
29+
name = "group"
30+
members = [
31+
data.coderd_user.admin.id,
32+
resource.coderd_user.manager.id
33+
]
34+
}
35+
36+
resource "coderd_template" "example" {
37+
name = "example-template"
38+
versions = [{
39+
directory = "./example-template"
40+
active = true
41+
tf_vars = [{
42+
name = "image_id"
43+
value = "ami-12345678"
44+
}]
45+
# Version names can be randomly generated if null/omitted
46+
}]
47+
acl = {
48+
groups = [{
49+
id = data.coderd_organization.default.id
50+
role = "use"
51+
},
52+
{
53+
id = resource.coderd_group.bosses.id
54+
role = "admin"
55+
}]
56+
users = []
57+
}
58+
allow_user_cancel_workspace_jobs = false
59+
}

‎examples/resources/coderd_template/resource.tf

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,10 @@ resource "coderd_template" "ubuntu-main" {
2727
directory = "./staging-template"
2828
}
2929
]
30+
acl = {
31+
users = [{
32+
id = coderd_user.coder1.id
33+
role = "admin"
34+
}]
35+
}
3036
}

‎examples/resources/coderd_user/resource.tf

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ resource "coderd_user" "audit" {
2424
resource "coderd_user" "admin" {
2525
username = "admin"
2626
suspended = true
27+
email = "admin@example.com"
2728
}

‎examples/resources/coderd_workspace_proxy/resource.tf

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
resource "coderd_workspace_proxy" "sydney-wsp" {
2+
name = "sydney-wsp"
3+
display_name = "Australia (Sydney)"
4+
icon = "/emojis/1f1e6-1f1fa.png"
5+
}
6+
7+
resource "kubernetes_deployment" "syd_wsproxy" {
8+
metadata { /* ... */ }
9+
spec {
10+
template {
11+
metadata { /* ... */ }
12+
spec {
13+
container {
14+
name = "syd-wsp"
15+
image = "ghcr.io/coder/coder:latest"
16+
args = ["wsproxy", "server"]
17+
env {
18+
name = "CODER_PROXY_SESSION_TOKEN"
19+
value = coderd_workspace_proxy.sydney-wsp.session_token
20+
}
21+
/* ... */
22+
}
23+
/* ... */
24+
}
25+
}
26+
/* ... */
27+
}
28+
}

‎internal/provider/group_resource.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ func (r *GroupResource) Metadata(ctx context.Context, req resource.MetadataReque
6060

6161
func (r *GroupResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
6262
resp.Schema = schema.Schema{
63-
MarkdownDescription: "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.",
63+
MarkdownDescription: "A group on the Coder deployment.\n\nCreating groups requires an Enterprise license.",
6464

6565
Attributes: map[string]schema.Attribute{
6666
"id": schema.StringAttribute{
@@ -107,7 +107,7 @@ func (r *GroupResource) Schema(ctx context.Context, req resource.SchemaRequest,
107107
},
108108
},
109109
"members": schema.SetAttribute{
110-
MarkdownDescription: "Members of the group, by ID. If null, members will not be added or removed by Terraform.",
110+
MarkdownDescription: "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`",
111111
ElementType: UUIDType,
112112
Optional: true,
113113
},

‎internal/provider/provider.go

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,16 +53,18 @@ func (p *CoderdProvider) Metadata(ctx context.Context, req provider.MetadataRequ
5353
func (p *CoderdProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
5454
resp.Schema = schema.Schema{
5555
MarkdownDescription: `
56+
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.
57+
5658
~> **Warning**
5759
This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.10.1) and later.
5860
`,
5961
Attributes: map[string]schema.Attribute{
6062
"url": schema.StringAttribute{
61-
MarkdownDescription: "URL to the Coder deployment. Defaults to $CODER_URL.",
63+
MarkdownDescription: "URL to the Coder deployment. Defaults to `$CODER_URL`.",
6264
Optional: true,
6365
},
6466
"token": schema.StringAttribute{
65-
MarkdownDescription: "API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to $CODER_SESSION_TOKEN.",
67+
MarkdownDescription: "API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`.",
6668
Optional: true,
6769
},
6870
"default_organization_id": schema.StringAttribute{

‎internal/provider/template_resource.go

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -343,7 +343,7 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques
343343
Default: int64default.StaticInt64(0),
344344
},
345345
"time_til_dormant_ms": schema.Int64Attribute{
346-
MarkdownDescription: "Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.",
346+
MarkdownDescription: "(Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.",
347347
Optional: true,
348348
Computed: true,
349349
Default: int64default.StaticInt64(0),
@@ -361,13 +361,13 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques
361361
Default: booldefault.StaticBool(false),
362362
},
363363
"deprecation_message": schema.StringAttribute{
364-
MarkdownDescription: "If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it.",
364+
MarkdownDescription: "If set, the template will be marked as deprecated with the provided message and users will be blocked from creating new workspaces from it.",
365365
Optional: true,
366366
Computed: true,
367367
Default: stringdefault.StaticString(""),
368368
},
369369
"acl": schema.SingleNestedAttribute{
370-
MarkdownDescription: "(Enterprise) Access control list for the template. If null, ACL policies will not be added or removed by Terraform.",
370+
MarkdownDescription: "(Enterprise) Access control list for the template. If null, ACL policies will not be added, removed, or read by Terraform.",
371371
Optional: true,
372372
Attributes: map[string]schema.Attribute{
373373
"users": permissionAttribute,

0 commit comments

Comments
 (0)
Please sign in to comment.