docs: add secrets (#3057)

docs/secrets.md

@@ -0,0 +1,62 @@
+# Secrets
+
+<blockquote class="info">
+This article explains how to use secrets in a workspace. To authenticate the
+workspace provisioner, see <a href="./templates/authentication">this</a>.
+</blockquote>
+
+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
+
+<a href="./templates#parameters">Template parameters</a> 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.