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 8f38408

Browse files
ethanndicksonethanndickson
committedAug 21, 2024·
docs: add examples for all resources & data sources
1 parent dfa7472 commit 8f38408

File tree

20 files changed

+377
-17
lines changed

20 files changed

+377
-17
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: 23 additions & 1 deletion
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

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: 68 additions & 2 deletions
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 = "manager@example.com"
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

Lines changed: 5 additions & 2 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+
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

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

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"]
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: 19 additions & 0 deletions
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

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

‎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"]
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: 1 addition & 1 deletion
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\nTo 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.",
6464

6565
Attributes: map[string]schema.Attribute{
6666
"id": schema.StringAttribute{

‎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 and users will be blocked from creating new workspaces from it. The provided message will be displayed.",
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 inspected by Terraform.",
371371
Optional: true,
372372
Attributes: map[string]schema.Attribute{
373373
"users": permissionAttribute,

0 commit comments

Comments
 (0)
Please sign in to comment.