From 080352d52fd4c8e684cdaf8e64c44a11b92e0612 Mon Sep 17 00:00:00 2001 From: Ethan Dickson Date: Tue, 13 Aug 2024 05:38:28 +0000 Subject: [PATCH] chore: update readme, add version warnings, examples --- README.md | 63 +++++-------------- docs/data-sources/group.md | 4 +- docs/data-sources/organization.md | 9 ++- docs/data-sources/user.md | 4 +- docs/index.md | 12 ++-- docs/resources/group.md | 28 ++++++++- docs/resources/template.md | 35 ++++++++++- docs/resources/user.md | 32 +++++++++- examples/README.md | 9 --- .../coderd_example/data-source.tf | 3 - examples/provider/provider.tf | 3 - examples/resources/coderd_example/resource.tf | 3 - examples/resources/coderd_group/resource.tf | 23 +++++++ .../resources/coderd_template/resource.tf | 30 +++++++++ examples/resources/coderd_user/resource.tf | 27 ++++++++ internal/provider/group_data_source.go | 2 +- internal/provider/organization_data_source.go | 6 +- internal/provider/provider.go | 4 ++ internal/provider/user_data_source.go | 2 +- 19 files changed, 214 insertions(+), 85 deletions(-) delete mode 100644 examples/README.md delete mode 100644 examples/data-sources/coderd_example/data-source.tf delete mode 100644 examples/provider/provider.tf delete mode 100644 examples/resources/coderd_example/resource.tf create mode 100644 examples/resources/coderd_group/resource.tf create mode 100644 examples/resources/coderd_template/resource.tf create mode 100644 examples/resources/coderd_user/resource.tf diff --git a/README.md b/README.md index e11186c..8eeafa0 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,23 @@ -# Coderd Terraform Provider +# terraform-provider-coderd -# ⚠️ WORK IN PROGRESS - DO NOT USE ⚠️ +`terraform-provider-coderd` enables managing a [Coder](https://github.com/coder/coder) deployment using [Terraform](https://github.com/hashicorp/terraform) IaC. -_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._ - -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: - -- A resource and a data source (`internal/provider/`), -- Examples (`examples/`) and generated documentation (`docs/`), -- Miscellaneous meta files. - -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._ - -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. - -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. +The provider currently supports resources and data sources for: +- Users +- Templates + Template Versions +- Groups +- Workspace Proxies +- Organizations (Data Source only) ## Requirements - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.0 - [Go](https://golang.org/doc/install) >= 1.21 +- [Coder](https://github.com/coder/coder) >= 2.10.1 -## Building The Provider - -1. Clone the repository -1. Enter the repository directory -1. Build the provider using the Go `install` command: - -```shell -go install -``` - -## Adding Dependencies - -This provider uses [Go modules](https://github.com/golang/go/wiki/Modules). -Please see the Go documentation for the most up to date information about using Go modules. - -To add a new dependency `github.com/author/dependency` to your Terraform provider: - -```shell -go get github.com/author/dependency -go mod tidy -``` - -Then commit the changes to `go.mod` and `go.sum`. - -## Using the provider +## Usage -Fill this in for each provider +See the [`examples`](examples) and the [documentation](https://registry.terraform.io/providers/coder/coderd/latest/docs). ## Developing the Provider @@ -55,12 +25,11 @@ If you wish to work on the provider, you'll first need [Go](http://www.golang.or To compile the provider, run `go install`. This will build the provider and put the provider binary in the `$GOPATH/bin` directory. -To generate or update documentation, run `go generate`. +To generate or update documentation, run `make gen`. -In order to run the full suite of Acceptance tests, run `make testacc`. +### Terraform Acceptance Tests -*Note:* Acceptance tests create real resources, and often cost money to run. +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`. -```shell -make testacc -``` +> [!NOTE] +> Our [CI workflow](./github/workflows/test.yml) runs an acceptance test matrix against multiple Terraform versions. diff --git a/docs/data-sources/group.md b/docs/data-sources/group.md index eb790f5..37d3f7a 100644 --- a/docs/data-sources/group.md +++ b/docs/data-sources/group.md @@ -3,12 +3,12 @@ page_title: "coderd_group Data Source - terraform-provider-coderd" subcategory: "" description: |- - An existing group on the coder deployment. + An existing group on the Coder deployment. --- # coderd_group (Data Source) -An existing group on the coder deployment. +An existing group on the Coder deployment. diff --git a/docs/data-sources/organization.md b/docs/data-sources/organization.md index f1fcac6..26b8cdd 100644 --- a/docs/data-sources/organization.md +++ b/docs/data-sources/organization.md @@ -3,12 +3,17 @@ page_title: "coderd_organization Data Source - terraform-provider-coderd" subcategory: "" description: |- - An existing organization on the coder deployment. + An existing organization on the Coder deployment. + ~> Warning + This data source is only compatible with Coder version 2.13.0 https://github.com/coder/coder/releases/tag/v2.13.0 and later. --- # coderd_organization (Data Source) -An existing organization on the coder deployment. +An existing organization on the Coder deployment. + +~> **Warning** +This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later. diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md index b7b21db..35557e7 100644 --- a/docs/data-sources/user.md +++ b/docs/data-sources/user.md @@ -3,12 +3,12 @@ page_title: "coderd_user Data Source - terraform-provider-coderd" subcategory: "" description: |- - An existing user on the coder deployment + An existing user on the Coder deployment --- # coderd_user (Data Source) -An existing user on the coder deployment +An existing user on the Coder deployment diff --git a/docs/index.md b/docs/index.md index 974962c..d373b16 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,20 +3,16 @@ page_title: "coderd Provider" subcategory: "" description: |- - + ~> Warning + This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.13.0 and later. --- # coderd Provider +~> **Warning** +This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.13.0) and later. -## Example Usage - -```terraform -provider "coderd" { - # example configuration here -} -``` ## Schema diff --git a/docs/resources/group.md b/docs/resources/group.md index ec10901..3e7220a 100644 --- a/docs/resources/group.md +++ b/docs/resources/group.md @@ -10,7 +10,33 @@ description: |- 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. - +## Example Usage + +```terraform +// Provider populated from environment variables +provider "coderd" {} + +resource "coderd_user" "coder1" { + username = "coder1" + name = "Coder One" + email = "coder1@coder.com" +} + +resource "coderd_user" "coder2" { + username = "coder2" + name = "Coder One" + email = "coder2@coder.com" +} + +// Add two users to the group by their ID. +resource "coderd_group" "group1" { + name = "group1" + members = [ + coderd_user.coder1.id, + coderd_user.coder2.id + ] +} +``` ## Schema diff --git a/docs/resources/template.md b/docs/resources/template.md index 598f385..185e52e 100644 --- a/docs/resources/template.md +++ b/docs/resources/template.md @@ -10,7 +10,40 @@ description: |- A Coder template - +## Example Usage + +```terraform +// Provider populated from environment variables +provider "coderd" {} + +// Get the commit SHA of the configuration's git repository +variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" { + type = string +} + +resource "coderd_user" "coder1" { + username = "coder1" + name = "Coder One" + email = "coder1@coder.com" +} + +resource "coderd_template" "ubuntu-main" { + name = "ubuntu-main" + description = "The main template for developing on Ubuntu." + versions = [ + { + name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}" + description = "The stable version of the template." + directory = "./stable-template" + }, + { + name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}" + description = "The staging version of the template." + directory = "./staging-template" + } + ] +} +``` ## Schema diff --git a/docs/resources/user.md b/docs/resources/user.md index 5672928..dd54af7 100644 --- a/docs/resources/user.md +++ b/docs/resources/user.md @@ -10,7 +10,37 @@ description: |- A user on the Coder deployment. - +## Example Usage + +```terraform +// Provider populated from environemnt variables +provider "coderd" {} + +// Create a bot user for Jenkins +resource "coderd_user" "jenkins" { + username = "jenkins" + name = "Jenkins CI/CD" + email = "ci@example.com" + roles = ["template-admin"] + login_type = "none" +} + +// Keep the password of a user account up to date from an external source +resource "coderd_user" "audit" { + username = "auditor" + name = "Auditor" + email = "security@example.com" + roles = ["auditor"] + login_type = "password" + password = data.vault_password.auditor.value +} + +// Ensure the admin account is suspended +resource "coderd_user" "admin" { + username = "admin" + suspended = true +} +``` ## Schema diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index 026c42c..0000000 --- a/examples/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Examples - -This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. - -The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation. - -* **provider/provider.tf** example file for the provider index page -* **data-sources/`full data source name`/data-source.tf** example file for the named data source page -* **resources/`full resource name`/resource.tf** example file for the named data source page diff --git a/examples/data-sources/coderd_example/data-source.tf b/examples/data-sources/coderd_example/data-source.tf deleted file mode 100644 index db00893..0000000 --- a/examples/data-sources/coderd_example/data-source.tf +++ /dev/null @@ -1,3 +0,0 @@ -data "coderd_example" "example" { - configurable_attribute = "some-value" -} diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf deleted file mode 100644 index 8d3fb0e..0000000 --- a/examples/provider/provider.tf +++ /dev/null @@ -1,3 +0,0 @@ -provider "coderd" { - # example configuration here -} diff --git a/examples/resources/coderd_example/resource.tf b/examples/resources/coderd_example/resource.tf deleted file mode 100644 index ccfd842..0000000 --- a/examples/resources/coderd_example/resource.tf +++ /dev/null @@ -1,3 +0,0 @@ -resource "coderd_example" "example" { - configurable_attribute = "some-value" -} diff --git a/examples/resources/coderd_group/resource.tf b/examples/resources/coderd_group/resource.tf new file mode 100644 index 0000000..0909dc0 --- /dev/null +++ b/examples/resources/coderd_group/resource.tf @@ -0,0 +1,23 @@ +// Provider populated from environment variables +provider "coderd" {} + +resource "coderd_user" "coder1" { + username = "coder1" + name = "Coder One" + email = "coder1@coder.com" +} + +resource "coderd_user" "coder2" { + username = "coder2" + name = "Coder One" + email = "coder2@coder.com" +} + +// Add two users to the group by their ID. +resource "coderd_group" "group1" { + name = "group1" + members = [ + coderd_user.coder1.id, + coderd_user.coder2.id + ] +} diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf new file mode 100644 index 0000000..b95f23d --- /dev/null +++ b/examples/resources/coderd_template/resource.tf @@ -0,0 +1,30 @@ +// Provider populated from environment variables +provider "coderd" {} + +// Get the commit SHA of the configuration's git repository +variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" { + type = string +} + +resource "coderd_user" "coder1" { + username = "coder1" + name = "Coder One" + email = "coder1@coder.com" +} + +resource "coderd_template" "ubuntu-main" { + name = "ubuntu-main" + description = "The main template for developing on Ubuntu." + versions = [ + { + name = "stable-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}" + description = "The stable version of the template." + directory = "./stable-template" + }, + { + name = "staging-${var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA}" + description = "The staging version of the template." + directory = "./staging-template" + } + ] +} diff --git a/examples/resources/coderd_user/resource.tf b/examples/resources/coderd_user/resource.tf new file mode 100644 index 0000000..ed6e380 --- /dev/null +++ b/examples/resources/coderd_user/resource.tf @@ -0,0 +1,27 @@ +// Provider populated from environemnt variables +provider "coderd" {} + +// Create a bot user for Jenkins +resource "coderd_user" "jenkins" { + username = "jenkins" + name = "Jenkins CI/CD" + email = "ci@example.com" + roles = ["template-admin"] + login_type = "none" +} + +// Keep the password of a user account up to date from an external source +resource "coderd_user" "audit" { + username = "auditor" + name = "Auditor" + email = "security@example.com" + roles = ["auditor"] + login_type = "password" + password = data.vault_password.auditor.value +} + +// Ensure the admin account is suspended +resource "coderd_user" "admin" { + username = "admin" + suspended = true +} diff --git a/internal/provider/group_data_source.go b/internal/provider/group_data_source.go index 5af8998..95c8e6e 100644 --- a/internal/provider/group_data_source.go +++ b/internal/provider/group_data_source.go @@ -56,7 +56,7 @@ func (d *GroupDataSource) Metadata(ctx context.Context, req datasource.MetadataR func (d *GroupDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ - MarkdownDescription: "An existing group on the coder deployment.", + MarkdownDescription: "An existing group on the Coder deployment.", Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ diff --git a/internal/provider/organization_data_source.go b/internal/provider/organization_data_source.go index 8471adc..59b598c 100644 --- a/internal/provider/organization_data_source.go +++ b/internal/provider/organization_data_source.go @@ -46,7 +46,11 @@ func (d *OrganizationDataSource) Metadata(ctx context.Context, req datasource.Me func (d *OrganizationDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ - MarkdownDescription: "An existing organization on the coder deployment.", + MarkdownDescription: `An existing organization on the Coder deployment. + +~> **Warning** +This data source is only compatible with Coder version [2.13.0](https://github.com/coder/coder/releases/tag/v2.13.0) and later. +`, Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ diff --git a/internal/provider/provider.go b/internal/provider/provider.go index 456adb3..34272a9 100644 --- a/internal/provider/provider.go +++ b/internal/provider/provider.go @@ -52,6 +52,10 @@ func (p *CoderdProvider) Metadata(ctx context.Context, req provider.MetadataRequ func (p *CoderdProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) { resp.Schema = schema.Schema{ + MarkdownDescription: ` +~> **Warning** +This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.13.0) and later. +`, Attributes: map[string]schema.Attribute{ "url": schema.StringAttribute{ MarkdownDescription: "URL to the Coder deployment. Defaults to $CODER_URL.", diff --git a/internal/provider/user_data_source.go b/internal/provider/user_data_source.go index c1675a3..7c5846f 100644 --- a/internal/provider/user_data_source.go +++ b/internal/provider/user_data_source.go @@ -50,7 +50,7 @@ func (d *UserDataSource) Metadata(ctx context.Context, req datasource.MetadataRe func (d *UserDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) { resp.Schema = schema.Schema{ - MarkdownDescription: "An existing user on the coder deployment", + MarkdownDescription: "An existing user on the Coder deployment", // Validation handled by ConfigValidators Attributes: map[string]schema.Attribute{ pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy