diff --git a/docs/templates.md b/docs/templates.md index 9fac5e542f761..6c4651be64e0c 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -23,8 +23,6 @@ vim /main.tf coder templates ``` -> We recommend source controlling your templates. - ## Persistent and ephemeral resources Coder supports both ephemeral and persistent resources in workspaces. Ephemeral @@ -53,6 +51,42 @@ Templates often contain *parameters*. In Coder, there are two types of parameter each workspace, often personalization settings such as "preferred region" or "workspace image". + +## Best Practices + +### Template Changes + +We recommend source controlling your templates. + +### Authenticating with Cloud Providers + +Coder's provisioner process needs to authenticate with cloud provider APIs to provision +workspaces. We strongly advise against including credentials directly in your templates. You +can either pass credentials to the provisioner as parameters, or execute Coder +in an environment that is authenticated with the cloud provider. + +We encourage the latter where supported. This approach simplifies the template, keeps cloud +provider credentials out of Coder's database (making it a less valuable target for attackers), +and is compatible with agent-based authentication schemes (that handle credential rotation +and/or ensure the credentials are not written to disk). + +Cloud providers for which the Terraform provider supports authenticated environments include + + * [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) + * [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) + * [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) + * [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) + +Additional providers may be supported; check the +[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for +details. + +The way these generally work is via the credentials being available to Coder either in some +well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via +environment variables. It is usually sufficient to authenticate using the CLI or SDK for the +cloud provider before running Coder for this to work, but check the Terraform provider +documentation for details. + --- Next: [Workspaces](./workspaces.md) diff --git a/examples/templates/aws-linux/README.md b/examples/templates/aws-linux/README.md index bf50e661334bc..ab012d0f31b68 100644 --- a/examples/templates/aws-linux/README.md +++ b/examples/templates/aws-linux/README.md @@ -10,6 +10,13 @@ tags: [cloud, aws] Pick this template in `coder templates init` and follow instructions. +## Authentication + +This template assumes that coderd is run in an environment that is authenticated +with AWS. For example, run `aws configure import` to import credentials on the +system and user running coderd. For other ways to authenticate [consult the +Terraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#authentication-and-configuration). + ## Required permissions / policy This example policy allows Coder to create EC2 instances and modify instances provisioned by Coder. diff --git a/examples/templates/aws-linux/main.tf b/examples/templates/aws-linux/main.tf index 2a9d625c2634e..3d6666345658b 100644 --- a/examples/templates/aws-linux/main.tf +++ b/examples/templates/aws-linux/main.tf @@ -7,26 +7,6 @@ terraform { } } -variable "access_key" { - description = <= 0 + condition = var.step2_do_admin_ssh_key >= 0 error_message = "Invalid Digital Ocean SSH key ID, a number is required." } } @@ -98,7 +87,8 @@ variable "region" { # Configure the DigitalOcean Provider provider "digitalocean" { - token = var.step1_do_token + # Recommended: use environment variable DIGITALOCEAN_TOKEN with your personal access token when starting coderd + # alternatively, you can pass the token via a variable. } data "coder_workspace" "me" {} @@ -130,12 +120,12 @@ resource "digitalocean_droplet" "workspace" { coder_agent_token = coder_agent.dev.token }) # Required to provision Fedora. - ssh_keys = var.step3_do_admin_ssh_key > 0 ? [var.step3_do_admin_ssh_key] : [] + ssh_keys = var.step2_do_admin_ssh_key > 0 ? [var.step2_do_admin_ssh_key] : [] } # Temporarily disabled because it breaks SSH. (https://github.com/coder/coder/issues/1750) # resource "digitalocean_project_resources" "project" { -# project = var.step2_do_project_id +# project = var.step1_do_project_id # # Workaround for terraform plan when using count. # resources = length(digitalocean_droplet.workspace) > 0 ? [ # digitalocean_volume.home_volume.urn, diff --git a/examples/templates/gcp-linux/README.md b/examples/templates/gcp-linux/README.md index 7f28a1b63c975..1c8f3fb7e965c 100644 --- a/examples/templates/gcp-linux/README.md +++ b/examples/templates/gcp-linux/README.md @@ -3,3 +3,22 @@ name: Develop in Linux on Google Cloud description: Get started with Linux development on Google Cloud. tags: [cloud, google] --- + +# gcp-linux + +## Getting started + +Pick this template in `coder templates init` and follow instructions. + +## Authentication + +This template assumes that coderd is run in an environment that is authenticated +with Google Cloud. For example, run `gcloud auth application-default login` to import +credentials on the system and user running coderd. For other ways to authenticate +[consult the Terraform docs](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/getting_started#adding-credentials). + +## Required permissions / policy + +The user or service account used by the Terraform provisioner should have the following roles + +- Compute Admin diff --git a/examples/templates/gcp-linux/main.tf b/examples/templates/gcp-linux/main.tf index 3250ffeb75b9f..a53a29127bf2c 100644 --- a/examples/templates/gcp-linux/main.tf +++ b/examples/templates/gcp-linux/main.tf @@ -11,20 +11,8 @@ terraform { } } -variable "service_account" { - description = <