expand README files for examples (#1946)

examples/templates/aws-linux/README.md

@@ -6,9 +6,8 @@ tags: [cloud, aws]
 
 # aws-linux
 
-## Getting started
-
-Pick this template in `coder templates init` and follow instructions.
+To get started, run `coder templates init`. When prompted, select this template.
+Follow the on-screen instructions to proceed.
 
 ## Authentication
 
@@ -19,7 +18,8 @@ Terraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/doc
 
 ## Required permissions / policy
 
-This example policy allows Coder to create EC2 instances and modify instances provisioned by Coder.
+The following sample policy allows Coder to create EC2 instances and modify
+instances provisioned by Coder:
 
 ```json
 {
@@ -68,4 +68,3 @@ This example policy allows Coder to create EC2 instances and modify instances pr
     ]
 }
 ```
-

examples/templates/aws-windows/README.md

@@ -8,7 +8,8 @@ tags: [cloud, aws]
 
 ## Getting started
 
-Pick this template in `coder templates init` and follow instructions.
+To get started, run `coder templates init`. When prompted, select this template.
+Follow the on-screen instructions to proceed.
 
 ## Authentication
 
@@ -19,7 +20,8 @@ Terraform docs](https://registry.terraform.io/providers/hashicorp/aws/latest/doc
 
 ## Required permissions / policy
 
-This example policy allows Coder to create EC2 instances and modify instances provisioned by Coder.
+The following sample policy allows Coder to create EC2 instances and modify
+instances provisioned by Coder:
 
 ```json
 {
@@ -68,4 +70,3 @@ This example policy allows Coder to create EC2 instances and modify instances pr
     ]
 }
 ```
-

examples/templates/do-linux/README.md

@@ -6,20 +6,30 @@ tags: [cloud, digitalocean]
 
 # do-linux
 
-This is an example for deploying workspaces as Digital Ocean Droplets.
+To deploy workspaces as DigitalOcean Droplets, you'll need:
 
-## Requirements
+- DigitalOcean [personal access token
+  (PAT)](https://docs.digitalocean.com/reference/api/create-personal-access-token/)
 
-- Digital Ocean Project ID (e.g. `doctl projects list`)
-  - Remove `variable "step2_do_project_id"` and `resource "digitalocean_project_resources" "project"` if you don't want project association.
-- (Optional) Digital Ocean SSH key ID (e.g. `doctl compute ssh-key list`)
-  - Only required for Fedora images to work.
+- DigitalOcean project ID (you can get your project information via the `doctl`
+  CLI by running `doctl projects list`)
+
+  - Remove the following sections from the `main.tf` file if you don't want to
+    associate your workspaces with a project:
+
+    - `variable "step2_do_project_id"`
+    - `resource "digitalocean_project_resources" "project"`
+
+- **Optional:** DigitalOcean SSH key ID (obtain via the `doctl` CLI by running
+  `doctl compute ssh-key list`)
+
+  - Note that this is only required for Fedora images to work.
 
 ## Authentication
 
 This template assumes that coderd is run in an environment that is authenticated
-with Digital Ocean. Obtain a
-[Digital Ocean Personal Access Token](https://cloud.digitalocean.com/account/api/tokens) and set
-the environment variable `DIGITALOCEAN_TOKEN` to the access token before starting coderd. For
-other ways to authenticate
-[consult the Terraform docs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).
+with Digital Ocean. Obtain a [Digital Ocean Personal Access
+Token](https://cloud.digitalocean.com/account/api/tokens) and set the
+environment variable `DIGITALOCEAN_TOKEN` to the access token before starting
+coderd. For other ways to authenticate [consult the Terraform
+docs](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs).

examples/templates/docker-image-builds/README.md

@@ -12,7 +12,8 @@ For large use cases, we recommend building images using CI/CD pipelines and regi
 
 ## Getting started
 
-Run `coder templates init` and select this template. Follow the instructions that appear.
+Run `coder templates init`. When prompted, select this template, and follow the
+on-screen instructions to proceed.
 
 ## Adding images
 

examples/templates/docker/README.md

@@ -6,19 +6,22 @@ tags: [local, docker]
 
 # docker
 
-## Getting started
-
-Run `coder templates init` and select this template. Follow the instructions that appear. 
+To get started, run `coder templates init`. When prompted, select this template.
+Follow the on-screen instructions to proceed.
 
 ## Adding/removing images
 
-After building and pushing an image to an image registry (e.g., DockerHub), you can edit the template to make the image available to users. 
-
-Edit the template:
+After building and pushing an image to an image registry (e.g., DockerHub), edit
+the template to make the image available to users:
 
 ```sh
+# Open the template
 vim main.tf
 ```
+
+Modify your file to match the following:
+
+```hcl
 variable "docker_image" {
   description = "What Docker image would you like to use for your workspace?"
   default     = "codercom/enterprise-base:ubuntu"
@@ -77,4 +80,3 @@ add the following features to your Coder template:
 - More
 
 We also welcome contributions!
-

examples/templates/gcp-linux/README.md

@@ -6,19 +6,40 @@ tags: [cloud, google]
 
 # gcp-linux
 
-## Getting started
-
-Pick this template in `coder templates init` and follow instructions.
+To get started, run `coder templates init`. When prompted, select this template,
+and follow the on-screen instructions to proceed.
 
 ## 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).
+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).
+
+## Service account
+
+Coder requires a Google Cloud Service Account to provision workspaces. To create
+a service account:
+
+1. Navigate to the [CGP
+   console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),
+   and select your Cloud project (if you have more than one project associated
+   with your account)
+
+1. Provide a service account name (this name is used to generate the service
+   account ID)
+
+1. Click **Create and continue**, and choose the following IAM roles to grant to
+   the service account:
+   - Compute Admin
+   - Service Account User
+
+   Click **Continue**.
 
-## Required permissions / policy
+1. Click on the created key, and navigate to the **Keys** tab.
 
-The user or service account used by the Terraform provisioner should have the following roles
+1. Click **Add key** > **Create new key**.
 
-- Compute Admin
+1. Generate a **JSON private key**, which will be what you provide to Coder
+   during the setup process.

examples/templates/gcp-vm-container/README.md

@@ -6,19 +6,40 @@ tags: [cloud, google, container]
 
 # gcp-vm-container
 
-## Getting started
-
-Pick this template in `coder templates init` and follow instructions.
+To get started, run `coder templates init`. When prompted, select this template,
+and follow the on-screen instructions to proceed.
 
 ## 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).
+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).
+
+## Service account
+
+Coder requires a Google Cloud Service Account to provision workspaces. To create
+a service account:
+
+1. Navigate to the [CGP
+   console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),
+   and select your Cloud project (if you have more than one project associated
+   with your account)
+
+1. Provide a service account name (this name is used to generate the service
+   account ID)
+
+1. Click **Create and continue**, and choose the following IAM roles to grant to
+   the service account:
+   - Compute Admin
+   - Service Account User
+
+   Click **Continue**.
 
-## Required permissions / policy
+1. Click on the created key, and navigate to the **Keys** tab.
 
-The user or service account used by the Terraform provisioner should have the following roles
+1. Click **Add key** > **Create new key**.
 
-- Compute Admin
+1. Generate a **JSON private key**, which will be what you provide to Coder
+   during the setup process.

examples/templates/gcp-windows/README.md

@@ -6,19 +6,40 @@ tags: [cloud, google]
 
 # gcp-windows
 
-## Getting started
-
-Pick this template in `coder templates init` and follow instructions.
+To get started, run `coder templates init`. When prompted, select this template,
+and follow the on-screen instructions to proceed.
 
 ## 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).
+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).
+
+## Service account
+
+Coder requires a Google Cloud Service Account to provision workspaces. To create
+a service account:
+
+1. Navigate to the [CGP
+   console](https://console.cloud.google.com/projectselector/iam-admin/serviceaccounts/create),
+   and select your Cloud project (if you have more than one project associated
+   with your account)
+
+1. Provide a service account name (this name is used to generate the service
+   account ID)
+
+1. Click **Create and continue**, and choose the following IAM roles to grant to
+   the service account:
+   - Compute Admin
+   - Service Account User
+
+   Click **Continue**.
 
-## Required permissions / policy
+1. Click on the created key, and navigate to the **Keys** tab.
 
-The user or service account used by the Terraform provisioner should have the following roles
+1. Click **Add key** > **Create new key**.
 
-- Compute Admin
+1. Generate a **JSON private key**, which will be what you provide to Coder
+   during the setup process.

examples/templates/kubernetes-multi-service/README.md

@@ -6,11 +6,12 @@ tags: [cloud, kubernetes]
 
 # Authentication
 
-This template has several ways to authenticate to a Kubernetes cluster.
+This template features two ways to authenticate to a Kubernetes cluster.
 
 ## kubeconfig (Coder host)
 
-If the Coder host has a local `~/.kube/config`, this can be used to authenticate with Coder. Make sure this is on the same user running the `coder` service.
+If the Coder host has a local `~/.kube/config`, you can use this to authenticate
+with Coder. Make sure this is done with same user that's running the `coder` service.
 
 ## ServiceAccount
 
@@ -52,26 +53,26 @@ Create a ServiceAccount and role on your cluster to authenticate your template w
     EOF
     ```
 
-   1. Use the following commands to fetch the values:
+1. Use the following commands to fetch the values:
 
-        **Cluster IP:**
+     **Cluster IP:**
 
-        ```sh
-        kubectl cluster-info | grep "control plane"
-        ```
+     ```sh
+     kubectl cluster-info | grep "control plane"
+     ```
 
-        **CA certificate**
+     **CA certificate**
 
-        ```sh
-        kubectl get secrets -n $CODER_NAMESPACE -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='coder')].data['ca\.crt']}{'\n'}"
-        ```
+     ```sh
+     kubectl get secrets -n $CODER_NAMESPACE -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='coder')].data['ca\.crt']}{'\n'}"
+     ```
 
-        **Token**
+     **Token**
 
-        ```sh
-        kubectl get secrets -n $CODER_NAMESPACE -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='coder')].data['token']}{'\n'}"
-        ```
+     ```sh
+     kubectl get secrets -n $CODER_NAMESPACE -o jsonpath="{.items[?(@.metadata.annotations['kubernetes\.io/service-account\.name']=='coder')].data['token']}{'\n'}"
+     ```
 
-        **Namespace**
+     **Namespace**
 
-        This should be the same as `$CODER_NAMESPACE`, set in step 1.
+     This should be the same as `$CODER_NAMESPACE`, set in step 1.