From 43b6d91e668d29e7257fec5ab83489c8becc71fa Mon Sep 17 00:00:00 2001 From: Ethan Dickson Date: Tue, 20 Aug 2024 06:04:43 +0000 Subject: [PATCH] docs: add examples for all resources & data sources --- docs/data-sources/group.md | 31 ++++++++ docs/data-sources/organization.md | 24 ++++++- docs/data-sources/template.md | 14 +++- docs/data-sources/user.md | 24 ++++++- docs/index.md | 70 ++++++++++++++++++- docs/resources/group.md | 7 +- docs/resources/template.md | 12 +++- docs/resources/user.md | 1 + docs/resources/workspace_proxy.md | 33 ++++++++- .../data-sources/coderd_group/data-source.tf | 28 ++++++++ .../coderd_organization/data-source.tf | 19 +++++ .../coderd_template/data-source.tf | 9 +++ .../data-sources/coderd_user/data-source.tf | 19 +++++ examples/provider/provider.tf | 60 ++++++++++++++++ .../resources/coderd_template/resource.tf | 6 ++ examples/resources/coderd_user/resource.tf | 1 + .../coderd_workspace_proxy/resource.tf | 28 ++++++++ internal/provider/group_resource.go | 2 +- internal/provider/provider.go | 6 +- internal/provider/template_resource.go | 6 +- 20 files changed, 383 insertions(+), 17 deletions(-) create mode 100644 examples/data-sources/coderd_group/data-source.tf create mode 100644 examples/data-sources/coderd_organization/data-source.tf create mode 100644 examples/data-sources/coderd_template/data-source.tf create mode 100644 examples/data-sources/coderd_user/data-source.tf create mode 100644 examples/provider/provider.tf create mode 100644 examples/resources/coderd_workspace_proxy/resource.tf diff --git a/docs/data-sources/group.md b/docs/data-sources/group.md index 37d3f7a..8a50e9e 100644 --- a/docs/data-sources/group.md +++ b/docs/data-sources/group.md @@ -10,7 +10,38 @@ description: |- An existing group on the Coder deployment. +## Example Usage +```terraform +// Get a group on the provider default organization by `id` +data "coderd_group" "employees" { + id = "abcd-efg-hijk" +} + +// Get a group on the provider default organization by `name` + `organization_id` +data "coderd_group" "bosses" { + name = "bosses" +} + +// Use them to apply ACL to a template +resource "coderd_template" "example" { + name = "example-template" + versions = [/* ... */] + acl = { + groups = [ + { + id = data.coderd_group.employees.id + role = "use" + }, + { + id = data.coderd_group.bosses.id + role = "admin" + } + ] + users = [] + } +} +``` ## Schema diff --git a/docs/data-sources/organization.md b/docs/data-sources/organization.md index 26b8cdd..d197410 100644 --- a/docs/data-sources/organization.md +++ b/docs/data-sources/organization.md @@ -15,7 +15,29 @@ 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. - +## Example Usage + +```terraform +// Get the default (first) organization for the coder deployment +data "coderd_organization" "default" { + is_default = true +} + +// Get another organization by `id` +data "coderd_organization" "example" { + id = "abcd-efg-hijk" +} + +data "coderd_organization" "example2" { + name = "example-organization-2" +} + +// Create a group on a specific organization +resource "coderd_group" "example" { + name = "example-group" + organization_id = data.coderd_organization.default.id +} +``` ## Schema diff --git a/docs/data-sources/template.md b/docs/data-sources/template.md index 33128fa..18e2d76 100644 --- a/docs/data-sources/template.md +++ b/docs/data-sources/template.md @@ -10,7 +10,19 @@ description: |- An existing template on the Coder deployment. - +## Example Usage + +```terraform +// Get a template on the provider's default organization by `id` +data "coderd_template" "example-template" { + id = "abcd-efg-hijk" +} + +// Get a template on the provider's default organization by `name` +data "coderd_template" "example-template2" { + name = "example-template-2" +} +``` ## Schema diff --git a/docs/data-sources/user.md b/docs/data-sources/user.md index 35557e7..366c16a 100644 --- a/docs/data-sources/user.md +++ b/docs/data-sources/user.md @@ -10,7 +10,29 @@ description: |- An existing user on the Coder deployment - +## Example Usage + +```terraform +// Get a user on the Coder deployment by `id` +data "coderd_user" "manager" { + id = "abcd-efg-hijk" +} + +// Get a user on the Coder deployment by `username` +data "coderd_user" "admin" { + username = "admin" +} + + +// Use them to create a group +resource "coderd_group" "bosses" { + name = "group" + members = [ + data.coderd_user.admin.id, + data.coderd_user.manager.id + ] +} +``` ## Schema diff --git a/docs/index.md b/docs/index.md index b9d4dc7..0dcf2dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,16 +3,82 @@ page_title: "coderd Provider" subcategory: "" description: |- + 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. ~> Warning This provider is only compatible with Coder version 2.10.1 https://github.com/coder/coder/releases/tag/v2.10.1 and later. --- # coderd Provider +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. + ~> **Warning** This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.10.1) and later. +## Example Usage + +```terraform +terraform { + required_providers { + coderd = { + source = "coder/coderd" + } + } +} + +provider "coderd" { + # `token` and `url` can be populated from environment variables. + # `default_organization_id` can be populated using + # the first organization the session token has access to. +} + + +data "coderd_organization" "default" { + is_default = true +} + +data "coderd_user" "admin" { + username = "admin" +} + +resource "coderd_user" "manager" { + username = "Manager" + email = "manager@example.com" +} + +resource "coderd_group" "bosses" { + name = "group" + members = [ + data.coderd_user.admin.id, + resource.coderd_user.manager.id + ] +} +resource "coderd_template" "example" { + name = "example-template" + versions = [{ + directory = "./example-template" + active = true + tf_vars = [{ + name = "image_id" + value = "ami-12345678" + }] + # Version names can be randomly generated if null/omitted + }] + acl = { + groups = [{ + id = data.coderd_organization.default.id + role = "use" + }, + { + id = resource.coderd_group.bosses.id + role = "admin" + }] + users = [] + } + allow_user_cancel_workspace_jobs = false +} +``` ## Schema @@ -20,5 +86,5 @@ This provider is only compatible with Coder version [2.10.1](https://github.com/ ### Optional - `default_organization_id` (String) Default organization ID to use when creating resources. Defaults to the first organization the token has access to. -- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to $CODER_SESSION_TOKEN. -- `url` (String) URL to the Coder deployment. Defaults to $CODER_URL. +- `token` (String) API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`. +- `url` (String) URL to the Coder deployment. Defaults to `$CODER_URL`. diff --git a/docs/resources/group.md b/docs/resources/group.md index 3e7220a..1bd5464 100644 --- a/docs/resources/group.md +++ b/docs/resources/group.md @@ -3,12 +3,15 @@ page_title: "coderd_group Resource - terraform-provider-coderd" subcategory: "" 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. + A group on the Coder deployment. + 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. --- # coderd_group (Resource) -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. +A group on the Coder deployment. + +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. ## Example Usage diff --git a/docs/resources/template.md b/docs/resources/template.md index 185e52e..89ce7ae 100644 --- a/docs/resources/template.md +++ b/docs/resources/template.md @@ -42,6 +42,12 @@ resource "coderd_template" "ubuntu-main" { directory = "./staging-template" } ] + acl = { + users = [{ + id = coderd_user.coder1.id + role = "admin" + }] + } } ``` @@ -55,7 +61,7 @@ resource "coderd_template" "ubuntu-main" { ### Optional -- `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)) +- `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)) - `activity_bump_ms` (Number) The activity bump duration for all workspaces created from this template, in milliseconds. Defaults to one hour. - `allow_user_auto_start` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true. - `allow_user_auto_stop` (Boolean) (Enterprise) Whether users can auto-start workspaces created from this template. Defaults to true. @@ -63,7 +69,7 @@ resource "coderd_template" "ubuntu-main" { - `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. - `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)) - `default_ttl_ms` (Number) The default time-to-live for all workspaces created from this template, in milliseconds. -- `deprecation_message` (String) If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it. +- `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. - `description` (String) A description of the template. - `display_name` (String) The display name of the template. Defaults to the template name. - `failure_ttl_ms` (Number) (Enterprise) The max lifetime before Coder stops all resources for failed workspaces created from this template, in milliseconds. @@ -71,7 +77,7 @@ resource "coderd_template" "ubuntu-main" { - `organization_id` (String) The ID of the organization. Defaults to the provider's default organization - `require_active_version` (Boolean) (Enterprise) Whether workspaces must be created from the active version of this template. Defaults to false. - `time_til_dormant_autodelete_ms` (Number) (Enterprise) The max lifetime before Coder permanently deletes dormant workspaces created from this template. -- `time_til_dormant_ms` (Number) Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds. +- `time_til_dormant_ms` (Number) (Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds. ### Read-Only diff --git a/docs/resources/user.md b/docs/resources/user.md index dd54af7..e1c6b68 100644 --- a/docs/resources/user.md +++ b/docs/resources/user.md @@ -39,6 +39,7 @@ resource "coderd_user" "audit" { resource "coderd_user" "admin" { username = "admin" suspended = true + email = "admin@example.com" } ``` diff --git a/docs/resources/workspace_proxy.md b/docs/resources/workspace_proxy.md index 53f2685..ad77a82 100644 --- a/docs/resources/workspace_proxy.md +++ b/docs/resources/workspace_proxy.md @@ -10,7 +10,38 @@ description: |- A Workspace Proxy for the Coder deployment. - +## Example Usage + +```terraform +resource "coderd_workspace_proxy" "sydney-wsp" { + name = "sydney-wsp" + display_name = "Australia (Sydney)" + icon = "/emojis/1f1e6-1f1fa.png" +} + +resource "kubernetes_deployment" "syd_wsproxy" { + metadata { /* ... */ } + spec { + template { + metadata { /* ... */ } + spec { + container { + name = "syd-wsp" + image = "ghcr.io/coder/coder:latest" + args = ["wsproxy", "server"] + env { + name = "CODER_PROXY_SESSION_TOKEN" + value = coderd_workspace_proxy.sydney-wsp.session_token + } + /* ... */ + } + /* ... */ + } + } + /* ... */ + } +} +``` ## Schema diff --git a/examples/data-sources/coderd_group/data-source.tf b/examples/data-sources/coderd_group/data-source.tf new file mode 100644 index 0000000..572e264 --- /dev/null +++ b/examples/data-sources/coderd_group/data-source.tf @@ -0,0 +1,28 @@ +// Get a group on the provider default organization by `id` +data "coderd_group" "employees" { + id = "abcd-efg-hijk" +} + +// Get a group on the provider default organization by `name` + `organization_id` +data "coderd_group" "bosses" { + name = "bosses" +} + +// Use them to apply ACL to a template +resource "coderd_template" "example" { + name = "example-template" + versions = [/* ... */] + acl = { + groups = [ + { + id = data.coderd_group.employees.id + role = "use" + }, + { + id = data.coderd_group.bosses.id + role = "admin" + } + ] + users = [] + } +} diff --git a/examples/data-sources/coderd_organization/data-source.tf b/examples/data-sources/coderd_organization/data-source.tf new file mode 100644 index 0000000..911bc99 --- /dev/null +++ b/examples/data-sources/coderd_organization/data-source.tf @@ -0,0 +1,19 @@ +// Get the default (first) organization for the coder deployment +data "coderd_organization" "default" { + is_default = true +} + +// Get another organization by `id` +data "coderd_organization" "example" { + id = "abcd-efg-hijk" +} + +data "coderd_organization" "example2" { + name = "example-organization-2" +} + +// Create a group on a specific organization +resource "coderd_group" "example" { + name = "example-group" + organization_id = data.coderd_organization.default.id +} diff --git a/examples/data-sources/coderd_template/data-source.tf b/examples/data-sources/coderd_template/data-source.tf new file mode 100644 index 0000000..b4befce --- /dev/null +++ b/examples/data-sources/coderd_template/data-source.tf @@ -0,0 +1,9 @@ +// Get a template on the provider's default organization by `id` +data "coderd_template" "example-template" { + id = "abcd-efg-hijk" +} + +// Get a template on the provider's default organization by `name` +data "coderd_template" "example-template2" { + name = "example-template-2" +} diff --git a/examples/data-sources/coderd_user/data-source.tf b/examples/data-sources/coderd_user/data-source.tf new file mode 100644 index 0000000..64a0345 --- /dev/null +++ b/examples/data-sources/coderd_user/data-source.tf @@ -0,0 +1,19 @@ +// Get a user on the Coder deployment by `id` +data "coderd_user" "manager" { + id = "abcd-efg-hijk" +} + +// Get a user on the Coder deployment by `username` +data "coderd_user" "admin" { + username = "admin" +} + + +// Use them to create a group +resource "coderd_group" "bosses" { + name = "group" + members = [ + data.coderd_user.admin.id, + data.coderd_user.manager.id + ] +} diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf new file mode 100644 index 0000000..ad80e7c --- /dev/null +++ b/examples/provider/provider.tf @@ -0,0 +1,60 @@ +terraform { + required_providers { + coderd = { + source = "coder/coderd" + } + } +} + +provider "coderd" { + # `token` and `url` can be populated from environment variables. + # `default_organization_id` can be populated using + # the first organization the session token has access to. +} + + +data "coderd_organization" "default" { + is_default = true +} + +data "coderd_user" "admin" { + username = "admin" +} + +resource "coderd_user" "manager" { + username = "Manager" + email = "manager@example.com" +} + +resource "coderd_group" "bosses" { + name = "group" + members = [ + data.coderd_user.admin.id, + resource.coderd_user.manager.id + ] +} + +resource "coderd_template" "example" { + name = "example-template" + versions = [{ + directory = "./example-template" + active = true + tf_vars = [{ + name = "image_id" + value = "ami-12345678" + }] + # Version names can be randomly generated if null/omitted + }] + acl = { + groups = [{ + id = data.coderd_organization.default.id + role = "use" + }, + { + id = resource.coderd_group.bosses.id + role = "admin" + }] + users = [] + } + allow_user_cancel_workspace_jobs = false +} diff --git a/examples/resources/coderd_template/resource.tf b/examples/resources/coderd_template/resource.tf index b95f23d..b8d05bd 100644 --- a/examples/resources/coderd_template/resource.tf +++ b/examples/resources/coderd_template/resource.tf @@ -27,4 +27,10 @@ resource "coderd_template" "ubuntu-main" { directory = "./staging-template" } ] + acl = { + users = [{ + id = coderd_user.coder1.id + role = "admin" + }] + } } diff --git a/examples/resources/coderd_user/resource.tf b/examples/resources/coderd_user/resource.tf index ed6e380..273d383 100644 --- a/examples/resources/coderd_user/resource.tf +++ b/examples/resources/coderd_user/resource.tf @@ -24,4 +24,5 @@ resource "coderd_user" "audit" { resource "coderd_user" "admin" { username = "admin" suspended = true + email = "admin@example.com" } diff --git a/examples/resources/coderd_workspace_proxy/resource.tf b/examples/resources/coderd_workspace_proxy/resource.tf new file mode 100644 index 0000000..9780854 --- /dev/null +++ b/examples/resources/coderd_workspace_proxy/resource.tf @@ -0,0 +1,28 @@ +resource "coderd_workspace_proxy" "sydney-wsp" { + name = "sydney-wsp" + display_name = "Australia (Sydney)" + icon = "/emojis/1f1e6-1f1fa.png" +} + +resource "kubernetes_deployment" "syd_wsproxy" { + metadata { /* ... */ } + spec { + template { + metadata { /* ... */ } + spec { + container { + name = "syd-wsp" + image = "ghcr.io/coder/coder:latest" + args = ["wsproxy", "server"] + env { + name = "CODER_PROXY_SESSION_TOKEN" + value = coderd_workspace_proxy.sydney-wsp.session_token + } + /* ... */ + } + /* ... */ + } + } + /* ... */ + } +} diff --git a/internal/provider/group_resource.go b/internal/provider/group_resource.go index 6c71b5b..0fbd155 100644 --- a/internal/provider/group_resource.go +++ b/internal/provider/group_resource.go @@ -60,7 +60,7 @@ func (r *GroupResource) Metadata(ctx context.Context, req resource.MetadataReque func (r *GroupResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) { resp.Schema = schema.Schema{ - 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.", + 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.", Attributes: map[string]schema.Attribute{ "id": schema.StringAttribute{ diff --git a/internal/provider/provider.go b/internal/provider/provider.go index 5c8bb43..651dcb4 100644 --- a/internal/provider/provider.go +++ b/internal/provider/provider.go @@ -53,16 +53,18 @@ 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: ` +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. + ~> **Warning** This provider is only compatible with Coder version [2.10.1](https://github.com/coder/coder/releases/tag/v2.10.1) and later. `, Attributes: map[string]schema.Attribute{ "url": schema.StringAttribute{ - MarkdownDescription: "URL to the Coder deployment. Defaults to $CODER_URL.", + MarkdownDescription: "URL to the Coder deployment. Defaults to `$CODER_URL`.", Optional: true, }, "token": schema.StringAttribute{ - MarkdownDescription: "API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to $CODER_SESSION_TOKEN.", + MarkdownDescription: "API token for communicating with the deployment. Most resource types require elevated permissions. Defaults to `$CODER_SESSION_TOKEN`.", Optional: true, }, "default_organization_id": schema.StringAttribute{ diff --git a/internal/provider/template_resource.go b/internal/provider/template_resource.go index 8ef046f..4584ec5 100644 --- a/internal/provider/template_resource.go +++ b/internal/provider/template_resource.go @@ -343,7 +343,7 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques Default: int64default.StaticInt64(0), }, "time_til_dormant_ms": schema.Int64Attribute{ - MarkdownDescription: "Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.", + MarkdownDescription: "(Enterprise) The max lifetime before Coder locks inactive workspaces created from this template, in milliseconds.", Optional: true, Computed: true, Default: int64default.StaticInt64(0), @@ -361,13 +361,13 @@ func (r *TemplateResource) Schema(ctx context.Context, req resource.SchemaReques Default: booldefault.StaticBool(false), }, "deprecation_message": schema.StringAttribute{ - MarkdownDescription: "If set, the template will be marked as deprecated and users will be blocked from creating new workspaces from it.", + 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.", Optional: true, Computed: true, Default: stringdefault.StaticString(""), }, "acl": schema.SingleNestedAttribute{ - MarkdownDescription: "(Enterprise) Access control list for the template. If null, ACL policies will not be added or removed by Terraform.", + MarkdownDescription: "(Enterprise) Access control list for the template. If null, ACL policies will not be added, removed, or inspected by Terraform.", Optional: true, Attributes: map[string]schema.Attribute{ "users": permissionAttribute,