docs: add coderd terraform provider (#14374)

This commit is contained in:
Ethan
2024-08-22 13:03:33 +10:00
committed by GitHub
parent 9f4f88f38c
commit d7800a43e9
7 changed files with 137 additions and 25 deletions

View File

@ -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 utilizes the same public REST API. There are several ways to extend/automate
Coder: Coder:
- [CLI](../reference/cli/README.md) - [coderd Terraform Provider](https://registry.terraform.io/providers/coder/coderd/latest)
- [REST API](../reference/api/README.md) - [CLI](../reference/cli)
- [REST API](../reference/api)
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk) - [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
## Quickstart ## Quickstart
@ -32,21 +33,25 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
## Documentation ## Documentation
We publish an [API reference](../reference/api/README.md) in our documentation. We publish an [API reference](../reference/api) in our documentation. You can
You can also enable a also enable a [Swagger endpoint](../reference/cli/server.md#--swagger-enable) on
[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder your Coder deployment.
deployment.
## Use cases ## Use cases
We strive to keep the following use cases up to date, but please note that 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 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 ### Templates
- [Update templates in CI](../templates/change-management.md): Store all - [Manage templates via Terraform or CLI](../templates/change-management.md):
templates and git and update templates in CI/CD pipelines. Store all templates in git and update them in CI/CD pipelines.
### Workspace agents ### Workspace agents

View File

@ -1,8 +1,9 @@
# Groups # Groups
Groups can be used with [template RBAC](./rbac.md) to give groups of users 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 access to specific templates. They can be defined via the Coder web UI,
[synced from your identity provider](./auth.md#group-sync-enterprise). [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) ![Groups](../images/groups.png)

View File

@ -1,8 +1,9 @@
# Role Based Access Control (RBAC) # Role Based Access Control (RBAC)
Use RBAC to define which users and [groups](./groups.md) can use specific Use RBAC to define which users and [groups](./groups.md) can use specific
templates in Coder. These can be defined in Coder or templates in Coder. These can be defined via the Coder web UI,
[synced from your identity provider](./auth.md) [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) ![rbac](../images/template-rbac.png)

View File

@ -26,8 +26,12 @@ Workspace proxies can be used in the browser by navigating to the user
## Requirements ## Requirements
- The [Coder CLI](../reference/cli/README.md) must be installed and - The [Coder CLI](../reference/cli) must be installed and authenticated as a
authenticated as a user with the Owner role. 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 ## Step 1: Create the proxy
@ -198,6 +202,49 @@ FROM ghcr.io/coder/coder:latest
ENTRYPOINT ["/opt/coder", "wsproxy", "server"] 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 ### Selecting a proxy
Users can select a workspace proxy at the top-right of the browser-based Coder Users can select a workspace proxy at the top-right of the browser-based Coder

View File

@ -333,7 +333,8 @@ could affect workspace users experience once the platform is live.
1. Establish dedicated accounts for users with the _Template Administrator_ 1. Establish dedicated accounts for users with the _Template Administrator_
role. role.
1. Maintain Coder templates using 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 1. Consider implementing a GitOps workflow to automatically push new template
versions into Coder from git. For example, on Github, you can use the versions into Coder from git. For example, on Github, you can use the
[Update Coder Template](https://github.com/marketplace/actions/update-coder-template) [Update Coder Template](https://github.com/marketplace/actions/update-coder-template)

View File

@ -1,7 +1,69 @@
# Template Change Management # Template Change Management
We recommend source-controlling your templates as you would other code. You can We recommend source-controlling your templates as you would other any code, and
[install Coder](../install/) in CI/CD pipelines to push new template versions. 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 ```console
# Install the Coder CLI # Install the Coder CLI
@ -25,8 +87,3 @@ coder templates push --yes $CODER_TEMPLATE_NAME \
--directory $CODER_TEMPLATE_DIR \ --directory $CODER_TEMPLATE_DIR \
--name=$CODER_TEMPLATE_VERSION # Version name is optional --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).

View File

@ -25,8 +25,8 @@ here!
![Starter templates](../images/templates/starter-templates.png) ![Starter templates](../images/templates/starter-templates.png)
If you prefer to use Coder on the [command line](../reference/cli/README.md), If you prefer to use Coder on the [command line](../reference/cli), use
use `coder templates init`. `coder templates init`.
> Coder starter templates are also available on our > Coder starter templates are also available on our
> [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates). > [GitHub repo](https://github.com/coder/coder/tree/main/examples/templates).