Updated authentication info

coder · matifali · Oct 16, 2023 · Aug 16, 2023 · Aug 17, 2023 · Aug 17, 2023
commit bf5228ca00fd2792961f9139863d307ea89438d5
diff --git a/docs/templates/authentication.md b/docs/templates/authentication.md
@@ -7,28 +7,39 @@
   </p>
 </blockquote>
 
-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.
+The Coder server's provisioner process needs to authenticate with
+cloud provider APIs to provision workspaces. There are two approaches
+to do this:
 
-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).
+- Pass credentials to the provisioner as parameters.
+- Preferred: Execute the Coder server in an environment that is
+authenticated with the cloud provider.
 
-Cloud providers for which the Terraform provider supports authenticated environments include
+We encourage the latter approach where supported. This 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, which handle credential
+rotation or ensure the credentials are not written to disk.
+
+Generally, you can set up an environment to provide credentials to Cover in these ways:
+
+- A well-known location on disk: For example, `~/.aws/credentials` for
+  AWS on POSIX systems.
+
+- 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.
+
+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.
+Additional providers may be supported. Check the [documentation of the
+Terraform provider](https://registry.terraform.io/browse/providers)
+for details.
diff --git a/docs/templates/change-management.md b/docs/templates/change-management.md
@@ -1,6 +1,8 @@
 # Template Change Management
 
-We recommend source controlling your templates as you would other code. [Install Coder](../install/) in CI/CD pipelines to push new template versions.
+We recommend source controlling your templates as you would other
+code. [Install Coder](../install/) in CI/CD pipelines to push new
+template versions.
 
 ```console
 # Install the Coder CLI