From c6ad14aa1b48517ef4ef06fa84c9c9633dacdbdf Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 31 May 2022 09:32:21 -0500 Subject: [PATCH 1/5] chore: update initial set of example READMEs --- examples/templates/aws-linux/README.md | 7 ++++--- examples/templates/aws-windows/README.md | 7 +++++++ examples/templates/docker/README.md | 14 ++++++++----- examples/templates/gcp-linux/README.md | 20 +++++++++++++++++++ examples/templates/gcp-vm-container/README.md | 20 +++++++++++++++++++ examples/templates/gcp-windows/README.md | 20 +++++++++++++++++++ 6 files changed, 80 insertions(+), 8 deletions(-) diff --git a/examples/templates/aws-linux/README.md b/examples/templates/aws-linux/README.md index bf50e661334bc..82cf3c3ed4671 100644 --- a/examples/templates/aws-linux/README.md +++ b/examples/templates/aws-linux/README.md @@ -8,11 +8,13 @@ tags: [cloud, aws] ## Getting started -Pick this template in `coder templates init` and follow instructions. +Run `coder templates init`, and when prompted, select this template. Follow the +on-screen instructions to proceed. ## 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 { @@ -61,4 +63,3 @@ This example policy allows Coder to create EC2 instances and modify instances pr ] } ``` - diff --git a/examples/templates/aws-windows/README.md b/examples/templates/aws-windows/README.md index 7644413148a50..19108b1688bd9 100644 --- a/examples/templates/aws-windows/README.md +++ b/examples/templates/aws-windows/README.md @@ -3,3 +3,10 @@ name: Develop in Windows on AWS description: Get started with Windows development on AWS. tags: [cloud, aws] --- + +# aws-windows + +## Getting started + +Run `coder templates init`, and when prompted, select this template. Follow the +on-screen instructions to proceed. diff --git a/examples/templates/docker/README.md b/examples/templates/docker/README.md index 3b52cda92d288..65eaf384a0be1 100644 --- a/examples/templates/docker/README.md +++ b/examples/templates/docker/README.md @@ -8,17 +8,22 @@ tags: [local, docker] ## Getting started -Run `coder templates init` and select this template. Follow the instructions that appear. +Run `coder templates init`, and 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: + +```dockerfile variable "docker_image" { description = "What Docker image would you like to use for your workspace?" default = "codercom/enterprise-base:ubuntu" @@ -77,4 +82,3 @@ add the following features to your Coder template: - More We also welcome contributions! - diff --git a/examples/templates/gcp-linux/README.md b/examples/templates/gcp-linux/README.md index 7f28a1b63c975..8b209f2ff0972 100644 --- a/examples/templates/gcp-linux/README.md +++ b/examples/templates/gcp-linux/README.md @@ -3,3 +3,23 @@ name: Develop in Linux on Google Cloud description: Get started with Linux development on Google Cloud. tags: [cloud, google] --- + +# gcp-linux + +## Getting Started + +Run `coder templates init`, and when prompted, select this template. Follow the +on-screen instructions to proceed. + +## 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). +2. Add the following roles: + - Compute Admin + - Service Account User +3. Click on the created key, and navigate to the **Keys** tab. +4. Click **Add key** > **Create new key**. +5. Generate a **JSON private key**, which will be what you provide to coder. diff --git a/examples/templates/gcp-vm-container/README.md b/examples/templates/gcp-vm-container/README.md index 75148e14d6cf3..6f00faaff9478 100644 --- a/examples/templates/gcp-vm-container/README.md +++ b/examples/templates/gcp-vm-container/README.md @@ -3,3 +3,23 @@ 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 + +Run `coder templates init`, and when prompted, select this template. Follow the +on-screen instructions to proceed. + +## 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). +2. Add the following roles: + - Compute Admin + - Service Account User +3. Click on the created key, and navigate to the **Keys** tab. +4. Click **Add key** > **Create new key**. +5. Generate a **JSON private key**, which will be what you provide to coder. diff --git a/examples/templates/gcp-windows/README.md b/examples/templates/gcp-windows/README.md index 3b0be9a82ac30..49afcae2c0146 100644 --- a/examples/templates/gcp-windows/README.md +++ b/examples/templates/gcp-windows/README.md @@ -3,3 +3,23 @@ name: Develop in Windows on Google Cloud description: Get started with Windows development on Google Cloud. tags: [cloud, google] --- + +# gcp-windows + +## Getting Started + +Run `coder templates init`, and when prompted, select this template. Follow the +on-screen instructions to proceed. + +## 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). +2. Add the following roles: + - Compute Admin + - Service Account User +3. Click on the created key, and navigate to the **Keys** tab. +4. Click **Add key** > **Create new key**. +5. Generate a **JSON private key**, which will be what you provide to coder. From b4a6a7a29a1a209f0ea9e3d8a0a43c008724a0e2 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Tue, 31 May 2022 13:45:35 -0500 Subject: [PATCH 2/5] chore: expand, edit AWS examples' README files --- examples/templates/aws-windows/README.md | 53 ++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/examples/templates/aws-windows/README.md b/examples/templates/aws-windows/README.md index 19108b1688bd9..1a784bc3c3100 100644 --- a/examples/templates/aws-windows/README.md +++ b/examples/templates/aws-windows/README.md @@ -10,3 +10,56 @@ tags: [cloud, aws] Run `coder templates init`, and when prompted, select this template. Follow the on-screen instructions to proceed. + +## Required permissions / policy + +The following sample 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" + } + } + } + ] +} +``` From 46afc5518045225e5d1c5baf7ed4a58f8ccc7ec8 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Wed, 1 Jun 2022 09:19:40 -0500 Subject: [PATCH 3/5] chore: edit README files for examples --- examples/templates/aws-linux/README.md | 6 ++-- examples/templates/aws-windows/README.md | 4 +-- examples/templates/do-linux/README.md | 20 ++++++++----- .../templates/docker-image-builds/README.md | 3 +- examples/templates/docker/README.md | 6 ++-- examples/templates/gcp-linux/README.md | 30 +++++++++++++------ examples/templates/gcp-vm-container/README.md | 30 +++++++++++++------ examples/templates/gcp-windows/README.md | 30 +++++++++++++------ .../kubernetes-multi-service/README.md | 5 ++-- 9 files changed, 87 insertions(+), 47 deletions(-) diff --git a/examples/templates/aws-linux/README.md b/examples/templates/aws-linux/README.md index 82cf3c3ed4671..9e7e6421481f8 100644 --- a/examples/templates/aws-linux/README.md +++ b/examples/templates/aws-linux/README.md @@ -6,10 +6,8 @@ tags: [cloud, aws] # aws-linux -## Getting started - -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template. +Follow the on-screen instructions to proceed. ## Required permissions / policy diff --git a/examples/templates/aws-windows/README.md b/examples/templates/aws-windows/README.md index 1a784bc3c3100..9ca2792f56aee 100644 --- a/examples/templates/aws-windows/README.md +++ b/examples/templates/aws-windows/README.md @@ -8,8 +8,8 @@ tags: [cloud, aws] ## Getting started -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template. +Follow the on-screen instructions to proceed. ## Required permissions / policy diff --git a/examples/templates/do-linux/README.md b/examples/templates/do-linux/README.md index 398b18501ba63..3800e73528253 100644 --- a/examples/templates/do-linux/README.md +++ b/examples/templates/do-linux/README.md @@ -6,12 +6,18 @@ 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 Personal Access Token (PAT) -- 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. diff --git a/examples/templates/docker-image-builds/README.md b/examples/templates/docker-image-builds/README.md index 332d22b5cda22..8d4792b96d5e0 100644 --- a/examples/templates/docker-image-builds/README.md +++ b/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 diff --git a/examples/templates/docker/README.md b/examples/templates/docker/README.md index 65eaf384a0be1..c3572369480e8 100644 --- a/examples/templates/docker/README.md +++ b/examples/templates/docker/README.md @@ -6,10 +6,8 @@ tags: [local, docker] # docker -## Getting started - -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template. +Follow the on-screen instructions to proceed. ## Adding/removing images diff --git a/examples/templates/gcp-linux/README.md b/examples/templates/gcp-linux/README.md index 8b209f2ff0972..9c299807662c5 100644 --- a/examples/templates/gcp-linux/README.md +++ b/examples/templates/gcp-linux/README.md @@ -6,20 +6,32 @@ tags: [cloud, google] # gcp-linux -## Getting Started - -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template, +and follow the on-screen instructions to proceed. ## 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). -2. Add the following roles: +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 -3. Click on the created key, and navigate to the **Keys** tab. -4. Click **Add key** > **Create new key**. -5. Generate a **JSON private key**, which will be what you provide to coder. + + Click **Continue**. + +1. Click on the created key, and navigate to the **Keys** tab. + +1. Click **Add key** > **Create new key**. + +1. Generate a **JSON private key**, which will be what you provide to Coder + during the setup process. diff --git a/examples/templates/gcp-vm-container/README.md b/examples/templates/gcp-vm-container/README.md index 6f00faaff9478..9d6ec0d43e8b8 100644 --- a/examples/templates/gcp-vm-container/README.md +++ b/examples/templates/gcp-vm-container/README.md @@ -6,20 +6,32 @@ tags: [cloud, google, container] # gcp-vm-container -## Getting Started - -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template, +and follow the on-screen instructions to proceed. ## 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). -2. Add the following roles: +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 -3. Click on the created key, and navigate to the **Keys** tab. -4. Click **Add key** > **Create new key**. -5. Generate a **JSON private key**, which will be what you provide to coder. + + Click **Continue**. + +1. Click on the created key, and navigate to the **Keys** tab. + +1. Click **Add key** > **Create new key**. + +1. Generate a **JSON private key**, which will be what you provide to Coder + during the setup process. diff --git a/examples/templates/gcp-windows/README.md b/examples/templates/gcp-windows/README.md index 49afcae2c0146..a84eba6d29d2e 100644 --- a/examples/templates/gcp-windows/README.md +++ b/examples/templates/gcp-windows/README.md @@ -6,20 +6,32 @@ tags: [cloud, google] # gcp-windows -## Getting Started - -Run `coder templates init`, and when prompted, select this template. Follow the -on-screen instructions to proceed. +To get started, run `coder templates init`. When prompted, select this template, +and follow the on-screen instructions to proceed. ## 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). -2. Add the following roles: +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 -3. Click on the created key, and navigate to the **Keys** tab. -4. Click **Add key** > **Create new key**. -5. Generate a **JSON private key**, which will be what you provide to coder. + + Click **Continue**. + +1. Click on the created key, and navigate to the **Keys** tab. + +1. Click **Add key** > **Create new key**. + +1. Generate a **JSON private key**, which will be what you provide to Coder + during the setup process. diff --git a/examples/templates/kubernetes-multi-service/README.md b/examples/templates/kubernetes-multi-service/README.md index dd9944f4b227e..ed7147590c861 100644 --- a/examples/templates/kubernetes-multi-service/README.md +++ b/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 From 6d285b0ff7a38cf49aa414e154e25d80e0bc5f56 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Thu, 2 Jun 2022 13:32:48 -0500 Subject: [PATCH 4/5] Apply suggestions from review Co-authored-by: Ben Potter --- examples/templates/docker/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/templates/docker/README.md b/examples/templates/docker/README.md index c3572369480e8..6a627472513c7 100644 --- a/examples/templates/docker/README.md +++ b/examples/templates/docker/README.md @@ -21,7 +21,7 @@ vim main.tf Modify your file to match the following: -```dockerfile +```hcl variable "docker_image" { description = "What Docker image would you like to use for your workspace?" default = "codercom/enterprise-base:ubuntu" From 428ca52b80abbd4d981b1335992ab3138a3b4c96 Mon Sep 17 00:00:00 2001 From: Katie Horne Date: Mon, 6 Jun 2022 12:29:37 -0500 Subject: [PATCH 5/5] chore: fix formatting --- .../kubernetes-multi-service/README.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/examples/templates/kubernetes-multi-service/README.md b/examples/templates/kubernetes-multi-service/README.md index ed7147590c861..3dda56db85099 100644 --- a/examples/templates/kubernetes-multi-service/README.md +++ b/examples/templates/kubernetes-multi-service/README.md @@ -53,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.