mirror of
https://github.com/coder/coder.git
synced 2025-07-09 11:45:56 +00:00
docs: add coderd terraform provider (#14374)
This commit is contained in:
@ -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
|
||||
|
||||
|
@ -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).
|
||||
|
||||

|
||||
|
||||
|
@ -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).
|
||||
|
||||

|
||||
|
||||
|
@ -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
|
||||
|
@ -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)
|
||||
|
71
docs/templates/change-management.md
vendored
71
docs/templates/change-management.md
vendored
@ -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).
|
||||
|
4
docs/templates/creating.md
vendored
4
docs/templates/creating.md
vendored
@ -25,8 +25,8 @@ here!
|
||||
|
||||

|
||||
|
||||
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).
|
||||
|
Reference in New Issue
Block a user