From f25c612aa8836bf2264663557a3bd0e724054d97 Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Wed, 20 Jul 2022 05:57:14 +0000 Subject: [PATCH 1/3] docs: add secrets --- docs/manifest.json | 10 ++++-- docs/secrets.md | 59 ++++++++++++++++++++++++++++++++ docs/templates/authentication.md | 2 +- 3 files changed, 68 insertions(+), 3 deletions(-) create mode 100644 docs/secrets.md diff --git a/docs/manifest.json b/docs/manifest.json index 048f8e5c8e873..a9f4ee7bed44b 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -62,7 +62,7 @@ "icon": " ", "children": [ { - "title": "Authentication & Secrets", + "title": "Provider Authentication", "description": "Learn how to authenticate the provisioner", "path": "./templates/authentication.md" } @@ -94,7 +94,13 @@ "path": "./dotfiles.md" }, { - "title": "User management", + "title": "Secrets", + "description": "Learn how to use secrets in your worskpace", + "icon": "<\/svg>", + "path": "./secrets.md" + }, + { + "title": "User Management", "description": "Learn about user roles available in Coder and how to create and manage users", "icon": "<\/svg>", "path": "./users.md" diff --git a/docs/secrets.md b/docs/secrets.md new file mode 100644 index 0000000000000..7aa384693ce96 --- /dev/null +++ b/docs/secrets.md @@ -0,0 +1,59 @@ +# Secrets + +
+This article explains how to use secrets in a workspace. To authenticate the +workspace provisioner, see this. +
+ +Coder takes an unopinionated stance to workspace secrets. + +## Wait a minute... + +Your first stab at secrets with Coder should be your local method. +You can do everything you can locally and more with your Coder workspace, so +whatever workflow and tools you already use to manage secrets can be brought +over. + +For most, this workflow is simply: + +1. Give your users their secrets in advance +1. They write them to a persistent file after + they've built a workspace + +Template parameters are a dangerous way to accept secrets. +We show parameters in cleartext around the product. Assume anyone with view +access to your workspace can also see parameters. + +## Dynamic Secrets + +Dynamic secrets are attached to the workspace lifecycle and require no setup by +the end user. + +They can be implemented in native Terraform like so: + +```hcl +resource "twilio_iam_api_key" "api_key" { + account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" + friendly_name = "Test API Key" +} + +resource "coder_agent" "dev" { + # ... + env = { + # Let users access the secret via #TWILIO_API_SECRET + TWILIO_API_SECRET = "${twilio_iam_api_key.api_key.secret}" + } +} +``` + +This method is limited to [services with Terraform providers](https://registry.terraform.io/browse/providers). + +A catch-all variation of this approach is dynamically provisioning a cloud service account (e.g [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key)) +for each workspace and then make the relevant secrets available via the cloud's secret management +system. + +## Coder SSH Key + +Coder automatically inserts an account-wide SSH key into each workspace. In MacOS +and Linux this key is at `~/.ssh/id_ecdsa`. You can view and +regenerate the key in the dashboard at Settings > SSH keys. diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md index 76f7f4c4d9d75..4f25be1711b74 100644 --- a/docs/templates/authentication.md +++ b/docs/templates/authentication.md @@ -1,4 +1,4 @@ -# Authentication & Secrets +# Provider Authentication

From 9eab5893cf4d552990cd4b9f8b0b708347e36bda Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Wed, 20 Jul 2022 06:00:54 +0000 Subject: [PATCH 2/3] improve English --- docs/secrets.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/secrets.md b/docs/secrets.md index 7aa384693ce96..32f72ccb28b64 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -22,14 +22,14 @@ For most, this workflow is simply: Template parameters are a dangerous way to accept secrets. We show parameters in cleartext around the product. Assume anyone with view -access to your workspace can also see parameters. +access to a workspace can also see its parameters. ## Dynamic Secrets Dynamic secrets are attached to the workspace lifecycle and require no setup by the end user. -They can be implemented in native Terraform like so: +They can be implemented in your template code like so: ```hcl resource "twilio_iam_api_key" "api_key" { @@ -40,7 +40,7 @@ resource "twilio_iam_api_key" "api_key" { resource "coder_agent" "dev" { # ... env = { - # Let users access the secret via #TWILIO_API_SECRET + # Let users access the secret via $TWILIO_API_SECRET TWILIO_API_SECRET = "${twilio_iam_api_key.api_key.secret}" } } @@ -49,7 +49,7 @@ resource "coder_agent" "dev" { This method is limited to [services with Terraform providers](https://registry.terraform.io/browse/providers). A catch-all variation of this approach is dynamically provisioning a cloud service account (e.g [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key)) -for each workspace and then make the relevant secrets available via the cloud's secret management +for each workspace and then making the relevant secrets available via the cloud's secret management system. ## Coder SSH Key From d5090293377141262bd6e6d69686fcd8135844eb Mon Sep 17 00:00:00 2001 From: Ammar Bandukwala Date: Wed, 20 Jul 2022 06:13:56 +0000 Subject: [PATCH 3/3] improve english moar --- docs/secrets.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/secrets.md b/docs/secrets.md index 32f72ccb28b64..6cb4003cc74b9 100644 --- a/docs/secrets.md +++ b/docs/secrets.md @@ -5,20 +5,20 @@ This article explains how to use secrets in a workspace. To authenticate the workspace provisioner, see this.

-Coder takes an unopinionated stance to workspace secrets. +Coder is open-minded about how you get your secrets into your workspaces. ## Wait a minute... Your first stab at secrets with Coder should be your local method. You can do everything you can locally and more with your Coder workspace, so -whatever workflow and tools you already use to manage secrets can be brought +whatever workflow and tools you already use to manage secrets may be brought over. For most, this workflow is simply: 1. Give your users their secrets in advance -1. They write them to a persistent file after - they've built a workspace +1. Your users write them to a persistent file after + they've built their workspace Template parameters are a dangerous way to accept secrets. We show parameters in cleartext around the product. Assume anyone with view @@ -26,10 +26,15 @@ access to a workspace can also see its parameters. ## Dynamic Secrets -Dynamic secrets are attached to the workspace lifecycle and require no setup by -the end user. +Dynamic secrets are attached to the workspace lifecycle and automatically +injected into the workspace. For a little bit of up front template work, +they make life simpler for both the end user and the security team. -They can be implemented in your template code like so: +This method is limited to +[services with Terraform providers](https://registry.terraform.io/browse/providers), +which excludes obscure API providers. + +Dynamic secrets can be implemented in your template code like so: ```hcl resource "twilio_iam_api_key" "api_key" { @@ -46,8 +51,6 @@ resource "coder_agent" "dev" { } ``` -This method is limited to [services with Terraform providers](https://registry.terraform.io/browse/providers). - A catch-all variation of this approach is dynamically provisioning a cloud service account (e.g [GCP](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/google_service_account_key#private_key)) for each workspace and then making the relevant secrets available via the cloud's secret management system.