coder · spikecurtis · Jun 3, 2022 · Jun 3, 2022 · Jun 3, 2022 · bpmct
diff --git a/docs/templates.md b/docs/templates.md
@@ -23,8 +23,6 @@ vim <template-name>/main.tf
 coder templates <create/update> <template-name>
 ```
 
-> 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
@@ -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
@@ -7,26 +7,6 @@ terraform {
   }
 }
 
-variable "access_key" {
-  description = <<EOT
-Create an AWS access key to provision resources with Coder:
-- https://console.aws.amazon.com/iam/home#/users
-
-See the template README for an example permissions policy,
-if needed.
-
-AWS Access Key ID
-EOT
-  sensitive   = true
-}
-
-variable "secret_key" {
-  description = <<EOT
-AWS Secret Key
-EOT
-  sensitive   = true
-}
-
 # Last updated 2022-05-31
 # aws ec2 describe-regions | jq -r '[.Regions[].RegionName] | sort'
 variable "region" {
@@ -70,9 +50,7 @@ variable "disk_size" {
 }
 
 provider "aws" {
-  region     = var.region
-  access_key = var.access_key
-  secret_key = var.secret_key
+  region = var.region
 }
 
 data "coder_workspace" "me" {

diff --git a/examples/templates/aws-windows/README.md b/examples/templates/aws-windows/README.md
@@ -3,3 +3,69 @@ name: Develop in Windows on AWS
 description: Get started with Windows development on AWS.
 tags: [cloud, aws]
 ---
+
+# aws-windows
+
+## 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 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.
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "VisualEditor0",
+            "Effect": "Allow",
+            "Action": [
+                "ec2:GetDefaultCreditSpecification",
+                "ec2:DescribeIamInstanceProfileAssociations",
+                "ec2:DescribeTags",
+                "ec2:CreateTags",
+                "ec2:RunInstances",
+                "ec2:DescribeInstanceCreditSpecifications",
+                "ec2:DescribeImages",
+                "ec2:ModifyDefaultCreditSpecification",
+                "ec2:DescribeVolumes"
+            ],
+            "Resource": "*"
+        },
+        {
+            "Sid": "CoderResouces",
+            "Effect": "Allow",
+            "Action": [
+                "ec2:DescribeInstances",
+                "ec2:DescribeInstanceAttribute",
+                "ec2:UnmonitorInstances",
+                "ec2:TerminateInstances",
+                "ec2:StartInstances",
+                "ec2:StopInstances",
+                "ec2:DeleteTags",
+                "ec2:MonitorInstances",
+                "ec2:CreateTags",
+                "ec2:RunInstances",
+                "ec2:ModifyInstanceAttribute",
+                "ec2:ModifyInstanceCreditSpecification"
+            ],
+            "Resource": "arn:aws:ec2:*:*:instance/*",
+            "Condition": {
+                "StringEquals": {
+                    "aws:ResourceTag/Coder_Provisioned": "true"
+                }
+            }
+        }
+    ]
+}
+```
+
diff --git a/examples/templates/aws-windows/main.tf b/examples/templates/aws-windows/main.tf
@@ -7,23 +7,6 @@ terraform {
   }
 }
 
-variable "access_key" {
-  description = <<EOT
-Create an AWS access key to provision resources with Coder:
-- https://console.aws.amazon.com/iam/home#/users
-
-AWS Access Key
-EOT
-  sensitive   = true
-}
-
-variable "secret_key" {
-  description = <<EOT
-AWS Secret Key
-EOT
-  sensitive   = true
-}
-
 # Last updated 2022-05-31
 # aws ec2 describe-regions | jq -r '[.Regions[].RegionName] | sort'
 variable "region" {
@@ -54,9 +37,7 @@ variable "region" {
 }
 
 provider "aws" {
-  region     = var.region
-  access_key = var.access_key
-  secret_key = var.secret_key
+  region = var.region
 }
 
 data "coder_workspace" "me" {

diff --git 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
@@ -11,20 +11,8 @@ terraform {
   }
 }
 
-variable "service_account" {
-  description = <<EOF
-Coder requires a Google Cloud Service Account to provision workspaces.
-
-1. Create a service account:
-   https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create
-2. Add the roles:
-   - Compute Admin
-   - Service Account User
-3. Click on the created key, and navigate to the "Keys" tab.
-4. Click "Add key", then "Create new key".
-5. Generate a JSON private key, and paste the contents below.
-EOF
-  sensitive   = true
+variable "project_id" {
+  description = "Which Google Compute Project should your workspace live in?"
 }
 
 variable "zone" {
@@ -37,9 +25,8 @@ variable "zone" {
 }
 
 provider "google" {
-  zone        = var.zone
-  credentials = var.service_account
-  project     = jsondecode(var.service_account).project_id
+  zone    = var.zone
+  project = var.project_id
 }
 
 data "google_compute_default_service_account" "default" {

diff --git a/examples/templates/gcp-vm-container/README.md b/examples/templates/gcp-vm-container/README.md
@@ -3,3 +3,22 @@ name: Develop in a container on a Google Cloud VM
 description: Get started with Linux development on Google Cloud.
 tags: [cloud, google, container]
 ---
+
+# gcp-vm-container
+
+## 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-vm-container/main.tf b/examples/templates/gcp-vm-container/main.tf
@@ -11,20 +11,8 @@ terraform {
   }
 }
 
-variable "service_account" {
-  description = <<EOF
-Coder requires a Google Cloud Service Account to provision workspaces.
-
-1. Create a service account:
-   https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create
-2. Add the roles:
-   - Compute Admin
-   - Service Account User
-3. Click on the created key, and navigate to the "Keys" tab.
-4. Click "Add key", then "Create new key".
-5. Generate a JSON private key, and paste the contents below.
-EOF
-  sensitive   = true
+variable "project_id" {
+  description = "Which Google Compute Project should your workspace live in?"
 }
 
 variable "zone" {
@@ -37,9 +25,8 @@ variable "zone" {
 }
 
 provider "google" {
-  zone        = var.zone
-  credentials = var.service_account
-  project     = jsondecode(var.service_account).project_id
+  zone    = var.zone
+  project = var.project_id
 }
 
 data "google_compute_default_service_account" "default" {

diff --git a/examples/templates/gcp-windows/README.md b/examples/templates/gcp-windows/README.md
@@ -3,3 +3,22 @@ name: Develop in Windows on Google Cloud
 description: Get started with Windows development on Google Cloud.
 tags: [cloud, google]
 ---
+
+# gcp-windows
+
+## 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-windows/main.tf b/examples/templates/gcp-windows/main.tf
@@ -11,20 +11,8 @@ terraform {
   }
 }
 
-variable "service_account" {
-  description = <<EOF
-Coder requires a Google Cloud Service Account to provision workspaces.
-
-1. Create a service account:
-   https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create
-2. Add the roles:
-   - Compute Admin
-   - Service Account User
-3. Click on the created key, and navigate to the "Keys" tab.
-4. Click "Add key", then "Create new key".
-5. Generate a JSON private key, and paste the contents below.
-EOF
-  sensitive   = true
+variable "project_id" {
+  description = "Which Google Compute Project should your workspace live in?"
 }
 
 variable "zone" {
@@ -37,9 +25,8 @@ variable "zone" {
 }
 
 provider "google" {
-  zone        = var.zone
-  credentials = var.service_account
-  project     = jsondecode(var.service_account).project_id
+  zone    = var.zone
+  project = var.project_id
 }
 
 data "coder_workspace" "me" {