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..6cb4003cc74b9 --- /dev/null +++ b/docs/secrets.md @@ -0,0 +1,62 @@ +# Secrets + +
+This article explains how to use secrets in a workspace. To authenticate the +workspace provisioner, see this. +
+ +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 may be brought +over. + +For most, this workflow is simply: + +1. Give your users their secrets in advance +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 +access to a workspace can also see its parameters. + +## Dynamic Secrets + +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. + +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" { + 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}" + } +} +``` + +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. + +## 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