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 = <