Skip to content

Commit d23df4c

Browse files
ethanndicksonethanndickson
authored
chore: update readme, add version warnings, examples (#71)
Closes #69.
1 parent bf2bf87 commit d23df4c

File tree

19 files changed

+214
-85
lines changed

19 files changed

+214
-85
lines changed

‎README.md

+16-47
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,35 @@
1-
# Coderd Terraform Provider
1+
# terraform-provider-coderd
22

3-
# ⚠️ WORK IN PROGRESS - DO NOT USE ⚠️
3+
`terraform-provider-coderd` enables managing a [Coder](https://github.com/coder/coder) deployment using [Terraform](https://github.com/hashicorp/terraform) IaC.
44

5-
_This template repository is built on the [Terraform Plugin Framework](https://github.com/hashicorp/terraform-plugin-framework). The template repository built on the [Terraform Plugin SDK](https://github.com/hashicorp/terraform-plugin-sdk) can be found at [terraform-provider-scaffolding](https://github.com/hashicorp/terraform-provider-scaffolding). See [Which SDK Should I Use?](https://developer.hashicorp.com/terraform/plugin/framework-benefits) in the Terraform documentation for additional information._
6-
7-
This repository is a *template* for a [Terraform](https://www.terraform.io) provider. It is intended as a starting point for creating Terraform providers, containing:
8-
9-
- A resource and a data source (`internal/provider/`),
10-
- Examples (`examples/`) and generated documentation (`docs/`),
11-
- Miscellaneous meta files.
12-
13-
These files contain boilerplate code that you will need to edit to create your own Terraform provider. Tutorials for creating Terraform providers can be found on the [HashiCorp Developer](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework) platform. _Terraform Plugin Framework specific guides are titled accordingly._
14-
15-
Please see the [GitHub template repository documentation](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) for how to create a new repository from this template on GitHub.
16-
17-
Once you've written your provider, you'll want to [publish it on the Terraform Registry](https://developer.hashicorp.com/terraform/registry/providers/publishing) so that others can use it.
5+
The provider currently supports resources and data sources for:
6+
- Users
7+
- Templates + Template Versions
8+
- Groups
9+
- Workspace Proxies
10+
- Organizations (Data Source only)
1811

1912
## Requirements
2013

2114
- [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0
2215
- [Go](https://golang.org/doc/install) >= 1.21
16+
- [Coder](https://github.com/coder/coder) >= 2.10.1
2317

24-
## Building The Provider
25-
26-
1. Clone the repository
27-
1. Enter the repository directory
28-
1. Build the provider using the Go `install` command:
29-
30-
```shell
31-
go install
32-
```
33-
34-
## Adding Dependencies
35-
36-
This provider uses [Go modules](https://github.com/golang/go/wiki/Modules).
37-
Please see the Go documentation for the most up to date information about using Go modules.
38-
39-
To add a new dependency `github.com/author/dependency` to your Terraform provider:
40-
41-
```shell
42-
go get github.com/author/dependency
43-
go mod tidy
44-
```
45-
46-
Then commit the changes to `go.mod` and `go.sum`.
47-
48-
## Using the provider
18+
## Usage
4919

50-
Fill this in for each provider
20+
See the [`examples`](examples) and the [documentation](https://registry.terraform.io/providers/coder/coderd/latest/docs).
5121

5222
## Developing the Provider
5323

5424
If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed on your machine (see [Requirements](#requirements) above).
5525

5626
To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory.
5727

58-
To generate or update documentation, run `go generate`.
28+
To generate or update documentation, run `make gen`.
5929

60-
In order to run the full suite of Acceptance tests, run `make testacc`.
30+
### Terraform Acceptance Tests
6131

62-
*Note:* Acceptance tests create real resources, and often cost money to run.
32+
Acceptance tests are run against a live Coder deployment in a local Docker container. To run the full suite of Acceptance tests, run `make testacc`.
6333

64-
```shell
65-
make testacc
66-
```
34+
> [!NOTE]
35+
> Our [CI workflow](./github/workflows/test.yml) runs an acceptance test matrix against multiple Terraform versions.

‎docs/data-sources/group.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
page_title: "coderd_group Data Source - terraform-provider-coderd"
44
subcategory: ""
55
description: |-
6-
An existing group on the coder deployment.
6+
An existing group on the Coder deployment.
77
---
88

99
# coderd_group (Data Source)
1010

11-
An existing group on the coder deployment.
11+
An existing group on the Coder deployment.
1212

1313

1414

‎docs/data-sources/organization.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,17 @@
33
page_title: "coderd_organization Data Source - terraform-provider-coderd"
44
subcategory: ""
55
description: |-
6-
An existing organization on the coder deployment.
6+
An existing organization on the Coder deployment.
7+
~> Warning
8+
This data source is only compatible with Coder version 2.13.0 https://github.com/coder/coder/releases/tag/v2.13.0 and later.
79
---
810

911
# coderd_organization (Data Source)
1012

11-
An existing organization on the coder deployment.
13+
An existing organization on the Coder deployment.
14+
15+
~> **Warning**
16+
This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
1217

1318

1419

‎docs/data-sources/user.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
page_title: "coderd_user Data Source - terraform-provider-coderd"
44
subcategory: ""
55
description: |-
6-
An existing user on the coder deployment
6+
An existing user on the Coder deployment
77
---
88

99
# coderd_user (Data Source)
1010

11-
An existing user on the coder deployment
11+
An existing user on the Coder deployment
1212

1313

1414

‎docs/index.md

+4-8
Original file line numberDiff line numberDiff line change
@@ -3,20 +3,16 @@
33
page_title: "coderd Provider"
44
subcategory: ""
55
description: |-
6-
6+
~> Warning
7+
This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.13.0 and later.
78
---
89

910
# coderd Provider
1011

12+
~> **Warning**
13+
This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.13.0) and later.
1114

1215

13-
## Example Usage
14-
15-
```terraform
16-
provider "coderd" {
17-
# example configuration here
18-
}
19-
```
2016

2117
<!-- schema generated by tfplugindocs -->
2218
## Schema

‎docs/resources/group.md

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

1111
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.
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
// Provider populated from environment variables
17+
provider "coderd" {}
18+
19+
resource "coderd_user" "coder1" {
20+
username = "coder1"
21+
name = "Coder One"
22+
email = "[email protected]"
23+
}
24+
25+
resource "coderd_user" "coder2" {
26+
username = "coder2"
27+
name = "Coder One"
28+
email = "[email protected]"
29+
}
30+
31+
// Add two users to the group by their ID.
32+
resource "coderd_group" "group1" {
33+
name = "group1"
34+
members = [
35+
coderd_user.coder1.id,
36+
coderd_user.coder2.id
37+
]
38+
}
39+
```
1440

1541
<!-- schema generated by tfplugindocs -->
1642
## Schema

‎docs/resources/template.md

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

1111
A Coder template
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
// Provider populated from environment variables
17+
provider "coderd" {}
18+
19+
// Get the commit SHA of the configuration's git repository
20+
variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" {
21+
type = string
22+
}
23+
24+
resource "coderd_user" "coder1" {
25+
username = "coder1"
26+
name = "Coder One"
27+
email = "[email protected]"
28+
}
29+
30+
resource "coderd_template" "ubuntu-main" {
31+
name = "ubuntu-main"
32+
description = "The main template for developing on Ubuntu."
33+
versions = [
34+
{
35+
name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
36+
description = "The stable version of the template."
37+
directory = "./stable-template"
38+
},
39+
{
40+
name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
41+
description = "The staging version of the template."
42+
directory = "./staging-template"
43+
}
44+
]
45+
}
46+
```
1447

1548
<!-- schema generated by tfplugindocs -->
1649
## Schema

‎docs/resources/user.md

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

1111
A user on the Coder deployment.
1212

13-
13+
## Example Usage
14+
15+
```terraform
16+
// Provider populated from environemnt variables
17+
provider "coderd" {}
18+
19+
// Create a bot user for Jenkins
20+
resource "coderd_user" "jenkins" {
21+
username = "jenkins"
22+
name = "Jenkins CI/CD"
23+
email = "[email protected]"
24+
roles = ["template-admin"]
25+
login_type = "none"
26+
}
27+
28+
// Keep the password of a user account up to date from an external source
29+
resource "coderd_user" "audit" {
30+
username = "auditor"
31+
name = "Auditor"
32+
email = "[email protected]"
33+
roles = ["auditor"]
34+
login_type = "password"
35+
password = data.vault_password.auditor.value
36+
}
37+
38+
// Ensure the admin account is suspended
39+
resource "coderd_user" "admin" {
40+
username = "admin"
41+
suspended = true
42+
}
43+
```
1444

1545
<!-- schema generated by tfplugindocs -->
1646
## Schema

‎examples/README.md

-9
This file was deleted.

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

-3
This file was deleted.

‎examples/provider/provider.tf

-3
This file was deleted.

‎examples/resources/coderd_example/resource.tf

-3
This file was deleted.

‎examples/resources/coderd_group/resource.tf

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Provider populated from environment variables
2+
provider "coderd" {}
3+
4+
resource "coderd_user" "coder1" {
5+
username = "coder1"
6+
name = "Coder One"
7+
email = "[email protected]"
8+
}
9+
10+
resource "coderd_user" "coder2" {
11+
username = "coder2"
12+
name = "Coder One"
13+
email = "[email protected]"
14+
}
15+
16+
// Add two users to the group by their ID.
17+
resource "coderd_group" "group1" {
18+
name = "group1"
19+
members = [
20+
coderd_user.coder1.id,
21+
coderd_user.coder2.id
22+
]
23+
}

‎examples/resources/coderd_template/resource.tf

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Provider populated from environment variables
2+
provider "coderd" {}
3+
4+
// Get the commit SHA of the configuration's git repository
5+
variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" {
6+
type = string
7+
}
8+
9+
resource "coderd_user" "coder1" {
10+
username = "coder1"
11+
name = "Coder One"
12+
email = "[email protected]"
13+
}
14+
15+
resource "coderd_template" "ubuntu-main" {
16+
name = "ubuntu-main"
17+
description = "The main template for developing on Ubuntu."
18+
versions = [
19+
{
20+
name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
21+
description = "The stable version of the template."
22+
directory = "./stable-template"
23+
},
24+
{
25+
name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}"
26+
description = "The staging version of the template."
27+
directory = "./staging-template"
28+
}
29+
]
30+
}

‎examples/resources/coderd_user/resource.tf

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Provider populated from environemnt variables
2+
provider "coderd" {}
3+
4+
// Create a bot user for Jenkins
5+
resource "coderd_user" "jenkins" {
6+
username = "jenkins"
7+
name = "Jenkins CI/CD"
8+
email = "[email protected]"
9+
roles = ["template-admin"]
10+
login_type = "none"
11+
}
12+
13+
// Keep the password of a user account up to date from an external source
14+
resource "coderd_user" "audit" {
15+
username = "auditor"
16+
name = "Auditor"
17+
email = "[email protected]"
18+
roles = ["auditor"]
19+
login_type = "password"
20+
password = data.vault_password.auditor.value
21+
}
22+
23+
// Ensure the admin account is suspended
24+
resource "coderd_user" "admin" {
25+
username = "admin"
26+
suspended = true
27+
}

‎internal/provider/group_data_source.go

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ func (d *GroupDataSource) Metadata(ctx context.Context, req datasource.MetadataR
5656

5757
func (d *GroupDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
5858
resp.Schema = schema.Schema{
59-
MarkdownDescription: "An existing group on the coder deployment.",
59+
MarkdownDescription: "An existing group on the Coder deployment.",
6060

6161
Attributes: map[string]schema.Attribute{
6262
"id": schema.StringAttribute{

0 commit comments

Comments
 (0)