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

|

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

|

|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -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)
|
||||||
|
71
docs/templates/change-management.md
vendored
71
docs/templates/change-management.md
vendored
@ -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).
|
|
||||||
|
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),
|
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).
|
||||||
|
Reference in New Issue
Block a user