diff --git a/docs/admin/automation.md b/docs/admin/automation.md index c89a114f03..ecfae8050e 100644 --- a/docs/admin/automation.md +++ b/docs/admin/automation.md @@ -4,8 +4,9 @@ All actions possible through the Coder dashboard can also be automated as it utilizes the same public REST API. There are several ways to extend/automate Coder: -- [CLI](../reference/cli/README.md) -- [REST API](../reference/api/README.md) +- [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest) +- [CLI](../reference/cli) +- [REST API](../reference/api) - [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk) ## Quickstart @@ -32,21 +33,25 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \ ## Documentation -We publish an [API reference](../reference/api/README.md) in our documentation. -You can also enable a -[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder -deployment. +We publish an [API reference](../reference/api) in our documentation. You can +also enable a [Swagger endpoint](../reference/cli/server.md#--swagger-enable) on +your Coder deployment. ## Use cases We strive to keep the following use cases up to date, but please note that changes to API queries and routes can occur. For the most recent queries and -payloads, we recommend checking the CLI and API documentation. +payloads, we recommend checking the relevant documentation. + +### Users & Groups + +- [Manage Users via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/user) +- [Manage Groups via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/group) ### Templates -- [Update templates in CI](../templates/change-management.md): Store all - templates and git and update templates in CI/CD pipelines. +- [Manage templates via Terraform or CLI](../templates/change-management.md): + Store all templates in git and update them in CI/CD pipelines. ### Workspace agents diff --git a/docs/admin/groups.md b/docs/admin/groups.md index 6d0c3ca765..b982e7d311 100644 --- a/docs/admin/groups.md +++ b/docs/admin/groups.md @@ -1,8 +1,9 @@ # Groups Groups can be used with [template RBAC](./rbac.md) to give groups of users -access to specific templates. They can be defined in Coder or -[synced from your identity provider](./auth.md#group-sync-enterprise). +access to specific templates. They can be defined via the Coder web UI, +[synced from your identity provider](./auth.md) or +[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template). ![Groups](../images/groups.png) diff --git a/docs/admin/rbac.md b/docs/admin/rbac.md index 554650ea67..86fd46a2bf 100644 --- a/docs/admin/rbac.md +++ b/docs/admin/rbac.md @@ -1,8 +1,9 @@ # Role Based Access Control (RBAC) Use RBAC to define which users and [groups](./groups.md) can use specific -templates in Coder. These can be defined in Coder or -[synced from your identity provider](./auth.md) +templates in Coder. These can be defined via the Coder web UI, +[synced from your identity provider](./auth.md) or +[managed via Terraform](https://registry.terraform.io/providers/coder/coderd/latest/docs/resources/template). ![rbac](../images/template-rbac.png) diff --git a/docs/admin/workspace-proxies.md b/docs/admin/workspace-proxies.md index 8d3114522f..7c9353765c 100644 --- a/docs/admin/workspace-proxies.md +++ b/docs/admin/workspace-proxies.md @@ -26,8 +26,12 @@ Workspace proxies can be used in the browser by navigating to the user ## Requirements -- The [Coder CLI](../reference/cli/README.md) must be installed and - authenticated as a user with the Owner role. +- The [Coder CLI](../reference/cli) must be installed and authenticated as a + user with the Owner role. +- Alternatively, the + [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest) + can be used to create and manage workspace proxies, if authenticated as a user + with the Owner role. ## Step 1: Create the proxy @@ -198,6 +202,49 @@ FROM ghcr.io/coder/coder:latest ENTRYPOINT ["/opt/coder", "wsproxy", "server"] ``` +### Managing via Terraform + +The +[coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest) +can also be used to create and manage workspace proxies in the same Terraform +configuration as your deployment. + +```hcl + +provider "coderd" { + url = "https://coder.example.com" + token = "****" +} + +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 + } + /* ... */ + } + /* ... */ + } + } + /* ... */ + } +} +``` + ### Selecting a proxy Users can select a workspace proxy at the top-right of the browser-based Coder diff --git a/docs/architecture/validated-arch.md b/docs/architecture/validated-arch.md index 70870203bc..ab5836404b 100644 --- a/docs/architecture/validated-arch.md +++ b/docs/architecture/validated-arch.md @@ -333,7 +333,8 @@ could affect workspace users experience once the platform is live. 1. Establish dedicated accounts for users with the _Template Administrator_ role. 1. Maintain Coder templates using - [version control](../templates/change-management.md). + [version control](../templates/change-management.md) and the + [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest/docs). 1. Consider implementing a GitOps workflow to automatically push new template versions into Coder from git. For example, on Github, you can use the [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md index 0ce27bcb5e..148745a14d 100644 --- a/docs/templates/change-management.md +++ b/docs/templates/change-management.md @@ -1,7 +1,69 @@ # Template Change Management -We recommend source-controlling your templates as you would other code. You can -[install Coder](../install/) in CI/CD pipelines to push new template versions. +We recommend source-controlling your templates as you would other any code, and +automating the creation of new versions in CI/CD pipelines. + +These pipelines will require tokens for your deployment. To cap token lifetime +on creation, +[configure Coder server to set a shorter max token lifetime](../reference/cli/server.md#--max-token-lifetime). + +## coderd Terraform Provider + +The +[coderd Terraform provider](https://registry.terraform.io/providers/coder/coderd/latest) +can be used to push new template versions, either manually, or in CI/CD +pipelines. To run the provider in a CI/CD pipeline, and to prevent drift, you'll +need to store the Terraform state +[remotely](https://developer.hashicorp.com/terraform/language/settings/backends/configuration). + +```hcl +terraform { + required_providers { + coderd = { + source = "coder/coderd" + } + } + backend "gcs" { + bucket = "example-bucket" + prefix = "terraform/state" + } +} + +provider "coderd" { + // Can be populated from environment variables + url = "https://coder.example.com" + token = "****" +} + +// Get the commit SHA of the configuration's git repository +variable "TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA" { + type = string +} + +resource "coderd_template" "kubernetes" { + name = "kubernetes" + description = "Develop in Kubernetes!" + versions = [{ + directory = ".coder/templates/kubernetes" + active = true + # Version name is optional + name = var.TFC_CONFIGURATION_VERSION_GIT_COMMIT_SHA + tf_vars = [{ + name = "namespace" + value = "default4" + }] + }] + /* ... Additional template configuration */ +} +``` + +For an example, see how we push our development image and template +[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml). + +## Coder CLI + +You can also [install Coder](../install/) to automate pushing new template +versions in CI/CD pipelines. ```console # Install the Coder CLI @@ -25,8 +87,3 @@ coder templates push --yes $CODER_TEMPLATE_NAME \ --directory $CODER_TEMPLATE_DIR \ --name=$CODER_TEMPLATE_VERSION # Version name is optional ``` - -To cap token lifetime on creation, -[configure Coder server to set a shorter max token lifetime](../reference/cli/server.md#--max-token-lifetime). -For an example, see how we push our development image and template -[with GitHub actions](https://github.com/coder/coder/blob/main/.github/workflows/dogfood.yaml). diff --git a/docs/templates/creating.md b/docs/templates/creating.md index 154a6c32d9..34ecd6cc30 100644 --- a/docs/templates/creating.md +++ b/docs/templates/creating.md @@ -25,8 +25,8 @@ here! ![Starter templates](../images/templates/starter-templates.png) -If you prefer to use Coder on the [command line](../reference/cli/README.md), -use `coder templates init`. +If you prefer to use Coder on the [command line](../reference/cli), use +`coder templates init`. > Coder starter templates are also available on our > [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).