diff --git a/docs/CONTRIBUTORS.md b/docs/CONTRIBUTORS.md deleted file mode 100644 index 2a6643991cc4d..0000000000000 --- a/docs/CONTRIBUTORS.md +++ /dev/null @@ -1,14 +0,0 @@ -# Contributors - - - -| Name | Start Date | First PR Date | Organization | GitHub User Link | -| ------------------- | :--------: | :-----------: | :-------------------------------: | ----------------------------------------------: | -| Grey Barkans | 01/13/2020 | 03/13/2022 | [Coder](https://github.com/coder) | [vapurrmaid](https://github.com/vapurrmaid) | -| Ben Potter | 08/10/2020 | 03/31/2022 | [Coder](https://github.com/coder) | [bpmct](https://github.com/bpmct) | -| Mathias Fredriksson | 04/25/2022 | 04/25/2022 | [Coder](https://github.com/coder) | [mafredri](https://github.com/mafredri) | -| Spike Curtis | 05/02/2022 | 05/06/2022 | [Coder](https://github.com/coder) | [spikecurtis](https://github.com/spikecurtis) | -| Kira Pilot | 05/09/2022 | 05/09/2022 | [Coder](https://github.com/coder) | [Kira-Pilot](https://github.com/Kira-Pilot) | -| David Wahler | 05/09/2022 | 04/05/2022 | [Coder](https://github.com/coder) | [dwahler](https://github.com/dwahler) | -| Abhineet Jain | 05/16/2022 | 05/16/2022 | [Coder](https://github.com/coder) | [abhineetjain](https://github.com/abhineetjain) | -| Lucy Satheesan | 05/23/2022 | 05/23/2022 | [Coder](https://github.com/coder) | [oxy](https://github.com/oxy) | diff --git a/docs/CODE_OF_CONDUCT.md b/docs/contributing/CODE_OF_CONDUCT.md similarity index 100% rename from docs/CODE_OF_CONDUCT.md rename to docs/contributing/CODE_OF_CONDUCT.md diff --git a/docs/SECURITY.md b/docs/contributing/SECURITY.md similarity index 100% rename from docs/SECURITY.md rename to docs/contributing/SECURITY.md diff --git a/docs/manifest.json b/docs/manifest.json index e4638d2af8ecb..3a346b5858cea 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -23,7 +23,14 @@ "title": "Templates", "description": "Learn about templates, which define the infrastructure underlying workspaces.", "path": "./templates.md", - "icon": " " + "icon": " ", + "children": [ + { + "title": "Authentication & Secrets", + "description": "Learn how to authenticate the provisioner", + "path": "./templates/authentication.md" + } + ] }, { "title": "Workspaces", @@ -40,12 +47,12 @@ { "title": "Code of Conduct", "description": "See the code of conduct for contributing to Coder.", - "path": "./CODE_OF_CONDUCT.md" + "path": "./contributing/CODE_OF_CONDUCT.md" }, { "title": "Security", "description": "How to report vulnerabilities in Coder", - "path": "./SECURITY.md" + "path": "./contributing/SECURITY.md" } ] } diff --git a/docs/quickstart.md b/docs/quickstart.md index 06b3f0141e259..a6c43e9b6b18d 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,7 +1,5 @@ # Quickstart -This guide will walk you through creating your first template and workspace. - ## Prerequisites Please [install Coder](./install.md) before proceeding with the steps outlined in this article. diff --git a/docs/templates.md b/docs/templates.md index c8d5a09bfe66d..9f0fc845ac31f 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -25,51 +25,24 @@ coder templates ## Parameters -Templates often contain *parameters*. In Coder, there are two types of parameters: +Templates often contain _parameters_. In Coder, there are two types of parameters: - **Admin parameters** are set when a template is created/updated. These values are often cloud secrets, such as a `ServiceAccount` token, and are annotated - with `sensitive = true` in the template code. - + with `sensitive = true` in the template code. - **User parameters** are set when a user creates a workspace. They are unique to each workspace, often personalization settings such as "preferred region" or "workspace image". -## Best Practices - -### Template Changes - -We recommend source controlling your templates. - -### Authenticating with Cloud Providers - -Coder's provisioner process needs to authenticate with cloud provider APIs to provision -workspaces. We strongly advise against including credentials directly in your templates. You -can either pass credentials to the provisioner as parameters, or execute Coder -in an environment that is authenticated with the cloud provider. +## Change Management -We encourage the latter where supported. This approach simplifies the template, keeps cloud -provider credentials out of Coder's database (making it a less valuable target for attackers), -and is compatible with agent-based authentication schemes (that handle credential rotation -and/or ensure the credentials are not written to disk). +We recommend source controlling your templates as you would other code. -Cloud providers for which the Terraform provider supports authenticated environments include: - -- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) -- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) -- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) -- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) - -Additional providers may be supported; check the -[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for -details. - -The way these generally work is via the credentials being available to Coder either in some -well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via -environment variables. It is usually sufficient to authenticate using the CLI or SDK for the -cloud provider before running Coder for this to work, but check the Terraform provider -documentation for details. +CI is as simple as running `coder templates update` with the appropriate +credentials. --- Next: [Workspaces](./workspaces.md) + +Next: [Authentication & Secrets](./authentication.md) diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md new file mode 100644 index 0000000000000..76f7f4c4d9d75 --- /dev/null +++ b/docs/templates/authentication.md @@ -0,0 +1,34 @@ +# Authentication & Secrets + +
+

+ Do not store secrets in templates. Assume every user has cleartext access + to every template. +

+
+ +Coder's provisioner process needs to authenticate with cloud provider APIs to provision +workspaces. You can either pass credentials to the provisioner as parameters or execute Coder +in an environment that is authenticated with the cloud provider. + +We encourage the latter where supported. This approach simplifies the template, keeps cloud +provider credentials out of Coder's database (making it a less valuable target for attackers), +and is compatible with agent-based authentication schemes (that handle credential rotation +and/or ensure the credentials are not written to disk). + +Cloud providers for which the Terraform provider supports authenticated environments include + +- [Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs) +- [Amazon Web Services](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) +- [Microsoft Azure](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs) +- [Kubernetes](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs) + +Additional providers may be supported; check the +[documentation of the Terraform provider](https://registry.terraform.io/browse/providers) for +details. + +The way these generally work is via the credentials being available to Coder either in some +well-known location on disk (e.g. `~/.aws/credentials` for AWS on posix systems), or via +environment variables. It is usually sufficient to authenticate using the CLI or SDK for the +cloud provider before running Coder for this to work, but check the Terraform provider +documentation for details.