Skip to content

docs: add secrets #3057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 20, 2022
Merged

docs: add secrets #3057

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f25c612
docs: add secrets
ammario Jul 20, 2022
9eab589
improve English
ammario Jul 20, 2022
d509029
improve english moar
ammario Jul 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
"icon": "<svg viewBox=\"0 0 16 16\" xmlns=\"http://www.w3.org/2000/svg\"> <path d=\"M15.0017 4.0017H1.0017C0.868289 3.99368 0.734692 4.01405 0.609732 4.06147C0.484772 4.10889 0.371292 4.18228 0.276784 4.27678C0.182276 4.37129 0.108891 4.48477 0.0614728 4.60973C0.0140548 4.73469 -0.00631686 4.86829 0.00170278 5.0017V15.0017C-0.00631686 15.1351 0.0140548 15.2687 0.0614728 15.3937C0.108891 15.5186 0.182276 15.6321 0.276784 15.7266C0.371292 15.8211 0.484772 15.8945 0.609732 15.9419C0.734692 15.9894 0.868289 16.0097 1.0017 16.0017H15.0017C15.1351 16.0097 15.2687 15.9894 15.3937 15.9419C15.5186 15.8945 15.6321 15.8211 15.7266 15.7266C15.8211 15.6321 15.8945 15.5186 15.9419 15.3937C15.9894 15.2687 16.0097 15.1351 16.0017 15.0017V5.0017C16.0097 4.86829 15.9894 4.73469 15.9419 4.60973C15.8945 4.48477 15.8211 4.37129 15.7266 4.27678C15.6321 4.18228 15.5186 4.10889 15.3937 4.06147C15.2687 4.01405 15.1351 3.99368 15.0017 4.0017ZM14.0017 14.0017H2.0017V6.0017H14.0017V14.0017Z\" /> <path d=\"M14 0H2V2H14V0Z\" fill=\"#333333\"/> <path d=\"M5 13L10 8L13 13H5Z\" /> <path d=\"M5 10C5.55228 10 6 9.55228 6 9C6 8.44772 5.55228 8 5 8C4.44772 8 4 8.44772 4 9C4 9.55228 4.44772 10 5 10Z\" /> </svg>",
"children": [
{
"title": "Authentication & Secrets",
"title": "Provider Authentication",
"description": "Learn how to authenticate the provisioner",
"path": "./templates/authentication.md"
}
Expand Down Expand Up @@ -94,7 +94,13 @@
"path": "./dotfiles.md"
},
{
"title": "User management",
"title": "Secrets",
"description": "Learn how to use secrets in your worskpace",
"icon": "<svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" height=\"24px\" viewBox=\"0 0 24 24\" width=\"24px\" fill=\"#000000\"><path d=\"M0 0h24v24H0zm0 0h24v24H0zm0 0h24v24H0zm0 0h24v24H0z\" fill=\"none\"\/><path d=\"M12 7c2.76 0 5 2.24 5 5 0 .65-.13 1.26-.36 1.83l2.92 2.92c1.51-1.26 2.7-2.89 3.43-4.75-1.73-4.39-6-7.5-11-7.5-1.4 0-2.74.25-3.98.7l2.16 2.16C10.74 7.13 11.35 7 12 7zM2 4.27l2.28 2.28.46.46C3.08 8.3 1.78 10.02 1 12c1.73 4.39 6 7.5 11 7.5 1.55 0 3.03-.3 4.38-.84l.42.42L19.73 22 21 20.73 3.27 3 2 4.27zM7.53 9.8l1.55 1.55c-.05.21-.08.43-.08.65 0 1.66 1.34 3 3 3 .22 0 .44-.03.65-.08l1.55 1.55c-.67.33-1.41.53-2.2.53-2.76 0-5-2.24-5-5 0-.79.2-1.53.53-2.2zm4.31-.78l3.15 3.15.02-.16c0-1.66-1.34-3-3-3l-.17.01z\"\/><\/svg>",
"path": "./secrets.md"
},
{
"title": "User Management",
"description": "Learn about user roles available in Coder and how to create and manage users",
"icon": "<svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><path d=\"M0 0h24v24H0z\" fill=\"none\"\/><path d=\"M16 11c1.66 0 2.99-1.34 2.99-3S17.66 5 16 5c-1.66 0-3 1.34-3 3s1.34 3 3 3zm-8 0c1.66 0 2.99-1.34 2.99-3S9.66 5 8 5C6.34 5 5 6.34 5 8s1.34 3 3 3zm0 2c-2.33 0-7 1.17-7 3.5V19h14v-2.5c0-2.33-4.67-3.5-7-3.5zm8 0c-.29 0-.62.02-.97.05 1.16.84 1.97 1.97 1.97 3.45V19h6v-2.5c0-2.33-4.67-3.5-7-3.5z\"\/><\/svg>",
"path": "./users.md"
Expand Down
62 changes: 62 additions & 0 deletions docs/secrets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
workspace provisioner, see <a href="./templates/authentication">this</a>.
workspace provisioner, see <a href="./templates/authentication">Provider Authentication</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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For most, this workflow is simply:
Often times, 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.
Comment on lines +23 to +25
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<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.
For most cases, we do not recommend using <a href="./templates#parameters">template parameters</a> to accept workspace secrets as anyone with view access to a workspace can also see its parameters.

Reasoning:

  1. Workspace params do not show up in the dashboard, CLI, or build log unless the template definition explicitly uses a parameter as label for a resource/coder_app. The same could be done with "secrets"
  • They may be fetchable via the API (cc @Emyrk)
  1. The only role that has read access to workspaces also has write access and can enter a terminal and env or cat project/.env to expose secrets

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Workspace params do not show up in the dashboard, CLI, or build log unless the template definition explicitly uses a parameter as label for a resource/coder_app. The same could be done with "secrets"

This is the case right now, but could change in the near future, so I left out the specifics.

The only role that has read access to workspaces also has write access and can enter a terminal and env or cat project/.env to expose secrets

The specific permission nodes seem likely to change in the near future as we build out RBAC. So, I phrased it in the safest way.


## 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,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
injected into the workspace. For a little bit of up front template work,
injected into the workspace. With a little bit of upfront 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.
2 changes: 1 addition & 1 deletion docs/templates/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Authentication & Secrets
# Provider Authentication

<blockquote class="danger">
<p>
Expand Down