From ea545e0aa2e1f823d27e5e5b69b4ec95f9cbbbd4 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 16 Jun 2022 11:51:16 -0500 Subject: [PATCH 1/2] chore: bump github.com/nhatthm/otelsql from 0.3.0 to 0.3.3 (#2415) Bumps [github.com/nhatthm/otelsql](https://github.com/nhatthm/otelsql) from 0.3.0 to 0.3.3. - [Release notes](https://github.com/nhatthm/otelsql/releases) - [Commits](https://github.com/nhatthm/otelsql/compare/v0.3.0...v0.3.3) --- updated-dependencies: - dependency-name: github.com/nhatthm/otelsql dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/quickstart.md | 2 -- docs/templates.md | 21 +++++++++++++-------- 2 files changed, 13 insertions(+), 10 deletions(-) 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..0c2016a7f063b 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -25,12 +25,11 @@ 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". @@ -41,14 +40,20 @@ Templates often contain *parameters*. In Coder, there are two types of parameter We recommend source controlling your templates. -### Authenticating with Cloud Providers +### 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. We strongly advise against including credentials directly in your templates. You -can either pass credentials to the provisioner as parameters, or execute Coder +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 +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). @@ -66,7 +71,7 @@ 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 +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. From d9e9a1ab08e932723ccb34c33512fd52bb746165 Mon Sep 17 00:00:00 2001 From: ammario Date: Thu, 16 Jun 2022 16:56:35 +0000 Subject: [PATCH 2/2] docs: a bunch of small touchups --- docs/CONTRIBUTORS.md | 14 ------- docs/{ => contributing}/CODE_OF_CONDUCT.md | 0 docs/{ => contributing}/SECURITY.md | 0 docs/manifest.json | 13 +++++-- docs/templates.md | 44 +++------------------- docs/templates/authentication.md | 34 +++++++++++++++++ 6 files changed, 50 insertions(+), 55 deletions(-) delete mode 100644 docs/CONTRIBUTORS.md rename docs/{ => contributing}/CODE_OF_CONDUCT.md (100%) rename docs/{ => contributing}/SECURITY.md (100%) create mode 100644 docs/templates/authentication.md 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/templates.md b/docs/templates.md index 0c2016a7f063b..9f0fc845ac31f 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -34,47 +34,15 @@ Templates often contain _parameters_. In Coder, there are two types of parameter to each workspace, often personalization settings such as "preferred region" or "workspace image". -## Best Practices +## Change Management -### Template Changes +We recommend source controlling your templates as you would other code. -We recommend source controlling your templates. - -### 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. +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.