Skip to content

Commit 35e6ac8

Browse files
stirbystirby
authored
docs: add missing code examples (#249)
* coder_env code example * added coder_script example * updated coder_script description to note parallelism * short coder_external_auth example * added external auth link, make gen * fixed icon link for coder_parameter * coder_provisioner example * fixed inline links for provisioner * added coder_workspace_owner examples
1 parent 60401e6 commit 35e6ac8

File tree

15 files changed

+282
-13
lines changed

15 files changed

+282
-13
lines changed

‎docs/data-sources/external_auth.md

+16-2
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,28 @@
33
page_title: "coder_external_auth Data Source - terraform-provider-coder"
44
subcategory: ""
55
description: |-
6-
Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)
6+
Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services https://coder.com/docs/admin/external-auth in a workspace. (e.g. Google Cloud, Github, Docker, etc.)
77
---
88

99
# coder_external_auth (Data Source)
1010

11-
Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)
11+
Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.)
1212

13+
## Example Usage
1314

15+
```terraform
16+
provider "coder" {}
17+
18+
19+
data "coder_external_auth" "github" {
20+
id = "github"
21+
}
22+
23+
data "coder_external_auth" "azure-identity" {
24+
id = "azure-identiy"
25+
optional = true
26+
}
27+
```
1428

1529
<!-- schema generated by tfplugindocs -->
1630
## Schema

‎docs/data-sources/parameter.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ data "coder_parameter" "home_volume_size" {
145145
- `description` (String) Describe what this parameter does.
146146
- `display_name` (String) The displayed name of the parameter as it will appear in the interface.
147147
- `ephemeral` (Boolean) The value of an ephemeral parameter will not be preserved between consecutive workspace builds.
148-
- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons here: https://github.com/coder/coder/tree/main/site/static/icon. Use a built-in icon with `data.coder_workspace.me.access_url + "/icon/<path>"`.
148+
- `icon` (String) A URL to an icon that will display in the dashboard. View built-in icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a built-in icon with `data.coder_workspace.me.access_url + "/icon/<path>"`.
149149
- `mutable` (Boolean) Whether this value can be changed after workspace creation. This can be destructive for values like region, so use with caution!
150150
- `option` (Block List, Max: 64) Each "option" block defines a value for a user to select from. (see [below for nested schema](#nestedblock--option))
151151
- `order` (Number) The order determines the position of a template parameter in the UI/CLI presentation. The lowest order is shown first and parameters with equal order are sorted by name (ascending order).

‎docs/data-sources/provisioner.md

+22-2
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,33 @@ description: |-
1010

1111
Use this data source to get information about the Coder provisioner.
1212

13+
## Example Usage
1314

15+
```terraform
16+
provider "coder" {}
17+
18+
data "coder_provisioner" "dev" {}
19+
20+
data "coder_workspace" "dev" {}
21+
22+
resource "coder_agent" "main" {
23+
arch = data.coder_provisioner.dev.arch
24+
os = data.coder_provisioner.dev.os
25+
dir = "/workspace"
26+
display_apps {
27+
vscode = true
28+
vscode_insiders = false
29+
web_terminal = true
30+
ssh_helper = false
31+
}
32+
}
33+
```
1434

1535
<!-- schema generated by tfplugindocs -->
1636
## Schema
1737

1838
### Read-Only
1939

20-
- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see https://pkg.go.dev/runtime#pkg-constants).
40+
- `arch` (String) The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).
2141
- `id` (String) The ID of this resource.
22-
- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see https://pkg.go.dev/runtime#pkg-constants).
42+
- `os` (String) The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).

‎docs/data-sources/workspace_owner.md

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

1111
Use this data source to fetch information about the workspace owner.
1212

13+
## Example Usage
1314

15+
```terraform
16+
provider "coder" {}
17+
18+
data "coder_workspace" "me" {}
19+
20+
data "coder_workspace_owner" "me" {}
21+
22+
resource "coder_agent" "dev" {
23+
arch = "amd64"
24+
os = "linux"
25+
dir = local.repo_dir
26+
env = {
27+
OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token,
28+
}
29+
}
30+
31+
# Add git credentials from coder_workspace_owner
32+
resource "coder_env" "git_author_name" {
33+
agent_id = coder_agent.agent_id
34+
name = "GIT_AUTHOR_NAME"
35+
value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
36+
}
37+
38+
resource "coder_env" "git_author_email" {
39+
agent_id = var.agent_id
40+
name = "GIT_AUTHOR_EMAIL"
41+
value = data.coder_workspace_owner.me.email
42+
count = data.coder_workspace_owner.me.email != "" ? 1 : 0
43+
}
44+
```
1445

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

‎docs/resources/env.md

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

1111
Use this resource to set an environment variable in a workspace. Note that this resource cannot be used to overwrite existing environment variables set on the "coder_agent" resource.
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
data "coder_workspace" "me" {}
17+
18+
resource "coder_agent" "dev" {
19+
os = "linux"
20+
arch = "amd64"
21+
dir = "/workspace"
22+
}
23+
24+
resource "coder_env" "welcome_message" {
25+
agent_id = coder_agent.dev.id
26+
name = "WELCOME_MESSAGE"
27+
value = "Welcome to your Coder workspace!"
28+
}
29+
30+
resource "coder_env" "internal_api_url" {
31+
agent_id = coder_agent.dev.id
32+
name = "INTERNAL_API_URL"
33+
value = "https://api.internal.company.com/v1"
34+
}
35+
```
1436

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

‎docs/resources/script.md

+57-2
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,69 @@
33
page_title: "coder_script Resource - terraform-provider-coder"
44
subcategory: ""
55
description: |-
6-
Use this resource to run a script from an agent.
6+
Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
77
---
88

99
# coder_script (Resource)
1010

11-
Use this resource to run a script from an agent.
11+
Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.
1212

13+
## Example Usage
1314

15+
```terraform
16+
data "coder_workspace" "me" {}
17+
18+
resource "coder_agent" "dev" {
19+
os = "linux"
20+
arch = "amd64"
21+
dir = "/workspace"
22+
}
23+
24+
resource "coder_script" "dotfiles" {
25+
agent_id = coder_agent.dev.agent_id
26+
display_name = "Dotfiles"
27+
icon = "/icon/dotfiles.svg"
28+
run_on_start = true
29+
script = templatefile("~/get_dotfiles.sh", {
30+
DOTFILES_URI : var.dotfiles_uri,
31+
DOTFILES_USER : var.dotfiles_user
32+
})
33+
}
34+
35+
resource "coder_script" "code-server" {
36+
agent_id = coder_agent.dev.agent_id
37+
display_name = "code-server"
38+
icon = "/icon/code.svg"
39+
run_on_start = true
40+
start_blocks_login = true
41+
script = templatefile("./install-code-server.sh", {
42+
LOG_PATH : "/tmp/code-server.log"
43+
})
44+
}
45+
46+
resource "coder_script" "nightly_sleep_reminder" {
47+
agent_id = coder_agent.dev.agent_id
48+
display_name = "Nightly update"
49+
icon = "/icon/database.svg"
50+
cron = "0 22 * * *"
51+
script = <<EOF
52+
#!/bin/sh
53+
echo "Running nightly update"
54+
sudo apt-get install
55+
EOF
56+
}
57+
58+
resource "coder_script" "shutdown" {
59+
agent_id = coder_agent.dev.id
60+
display_name = "Stop daemon server"
61+
run_on_stop = true
62+
icon = "/icons/memory.svg"
63+
script = <<EOF
64+
#!/bin/sh
65+
kill $(lsof -i :3002 -t) >/tmp/pid.log 2>&1 &
66+
EOF
67+
}
68+
```
1469

1570
<!-- schema generated by tfplugindocs -->
1671
## Schema

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

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
provider "coder" {}
2+
3+
4+
data "coder_external_auth" "github" {
5+
id = "github"
6+
}
7+
8+
data "coder_external_auth" "azure-identity" {
9+
id = "azure-identiy"
10+
optional = true
11+
}

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

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
provider "coder" {}
2+
3+
data "coder_provisioner" "dev" {}
4+
5+
data "coder_workspace" "dev" {}
6+
7+
resource "coder_agent" "main" {
8+
arch = data.coder_provisioner.dev.arch
9+
os = data.coder_provisioner.dev.os
10+
dir = "/workspace"
11+
display_apps {
12+
vscode = true
13+
vscode_insiders = false
14+
web_terminal = true
15+
ssh_helper = false
16+
}
17+
}

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

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
provider "coder" {}
2+
3+
data "coder_workspace" "me" {}
4+
5+
data "coder_workspace_owner" "me" {}
6+
7+
resource "coder_agent" "dev" {
8+
arch = "amd64"
9+
os = "linux"
10+
dir = local.repo_dir
11+
env = {
12+
OIDC_TOKEN : data.coder_workspace_owner.me.oidc_access_token,
13+
}
14+
}
15+
16+
# Add git credentials from coder_workspace_owner
17+
resource "coder_env" "git_author_name" {
18+
agent_id = coder_agent.agent_id
19+
name = "GIT_AUTHOR_NAME"
20+
value = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
21+
}
22+
23+
resource "coder_env" "git_author_email" {
24+
agent_id = var.agent_id
25+
name = "GIT_AUTHOR_EMAIL"
26+
value = data.coder_workspace_owner.me.email
27+
count = data.coder_workspace_owner.me.email != "" ? 1 : 0
28+
}

‎examples/resources/coder_env/resource.tf

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
data "coder_workspace" "me" {}
2+
3+
resource "coder_agent" "dev" {
4+
os = "linux"
5+
arch = "amd64"
6+
dir = "/workspace"
7+
}
8+
9+
resource "coder_env" "welcome_message" {
10+
agent_id = coder_agent.dev.id
11+
name = "WELCOME_MESSAGE"
12+
value = "Welcome to your Coder workspace!"
13+
}
14+
15+
resource "coder_env" "internal_api_url" {
16+
agent_id = coder_agent.dev.id
17+
name = "INTERNAL_API_URL"
18+
value = "https://api.internal.company.com/v1"
19+
}

‎examples/resources/coder_script/resource.tf

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
data "coder_workspace" "me" {}
2+
3+
resource "coder_agent" "dev" {
4+
os = "linux"
5+
arch = "amd64"
6+
dir = "/workspace"
7+
}
8+
9+
resource "coder_script" "dotfiles" {
10+
agent_id = coder_agent.dev.agent_id
11+
display_name = "Dotfiles"
12+
icon = "/icon/dotfiles.svg"
13+
run_on_start = true
14+
script = templatefile("~/get_dotfiles.sh", {
15+
DOTFILES_URI : var.dotfiles_uri,
16+
DOTFILES_USER : var.dotfiles_user
17+
})
18+
}
19+
20+
resource "coder_script" "code-server" {
21+
agent_id = coder_agent.dev.agent_id
22+
display_name = "code-server"
23+
icon = "/icon/code.svg"
24+
run_on_start = true
25+
start_blocks_login = true
26+
script = templatefile("./install-code-server.sh", {
27+
LOG_PATH : "/tmp/code-server.log"
28+
})
29+
}
30+
31+
resource "coder_script" "nightly_sleep_reminder" {
32+
agent_id = coder_agent.dev.agent_id
33+
display_name = "Nightly update"
34+
icon = "/icon/database.svg"
35+
cron = "0 22 * * *"
36+
script = <<EOF
37+
#!/bin/sh
38+
echo "Running nightly update"
39+
sudo apt-get install
40+
EOF
41+
}
42+
43+
resource "coder_script" "shutdown" {
44+
agent_id = coder_agent.dev.id
45+
display_name = "Stop daemon server"
46+
run_on_stop = true
47+
icon = "/icons/memory.svg"
48+
script = <<EOF
49+
#!/bin/sh
50+
kill $(lsof -i :3002 -t) >/tmp/pid.log 2>&1 &
51+
EOF
52+
}

‎provider/externalauth.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ func externalAuthDataSource() *schema.Resource {
1515
return &schema.Resource{
1616
SchemaVersion: 1,
1717

18-
Description: "Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to pre-authenticate external services in a workspace. (e.g. gcloud, gh, docker, etc)",
18+
Description: "Use this data source to require users to authenticate with an external service prior to workspace creation. This can be used to [pre-authenticate external services](https://coder.com/docs/admin/external-auth) in a workspace. (e.g. Google Cloud, Github, Docker, etc.)",
1919
ReadContext: func(ctx context.Context, rd *schema.ResourceData, i interface{}) diag.Diagnostics {
2020
id, ok := rd.Get("id").(string)
2121
if !ok || id == "" {

‎provider/parameter.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ func parameterDataSource() *schema.Resource {
220220
"icon": {
221221
Type: schema.TypeString,
222222
Description: "A URL to an icon that will display in the dashboard. View built-in " +
223-
"icons here: https://github.com/coder/coder/tree/main/site/static/icon. Use a " +
223+
"icons [here](https://github.com/coder/coder/tree/main/site/static/icon). Use a " +
224224
"built-in icon with `data.coder_workspace.me.access_url + \"/icon/<path>\"`.",
225225
ForceNew: true,
226226
Optional: true,

‎provider/provisioner.go

+2-2
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,12 @@ func provisionerDataSource() *schema.Resource {
2929
"os": {
3030
Type: schema.TypeString,
3131
Computed: true,
32-
Description: "The operating system of the host. This exposes `runtime.GOOS` (see https://pkg.go.dev/runtime#pkg-constants).",
32+
Description: "The operating system of the host. This exposes `runtime.GOOS` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).",
3333
},
3434
"arch": {
3535
Type: schema.TypeString,
3636
Computed: true,
37-
Description: "The architecture of the host. This exposes `runtime.GOARCH` (see https://pkg.go.dev/runtime#pkg-constants).",
37+
Description: "The architecture of the host. This exposes `runtime.GOARCH` (see [Go constants](https://pkg.go.dev/runtime#pkg-constants)).",
3838
},
3939
},
4040
}

‎provider/script.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ func scriptResource() *schema.Resource {
1717
return &schema.Resource{
1818
SchemaVersion: 1,
1919

20-
Description: "Use this resource to run a script from an agent.",
20+
Description: "Use this resource to run a script from an agent. When multiple scripts are assigned to the same agent, they are executed in parallel.",
2121
CreateContext: func(_ context.Context, rd *schema.ResourceData, _ interface{}) diag.Diagnostics {
2222
rd.SetId(uuid.NewString())
2323
runOnStart, _ := rd.Get("run_on_start").(bool)

0 commit comments

Comments
 (0)