website: document multi-provider

website/source/docs/configuration/providers.html.md

@@ -57,6 +57,46 @@ Within the block (the `{ }`) is configuration for the resource.
 The configuration is dependent on the type, and is documented
 [for each provider](/docs/providers/index.html).
 
+## Multiple Provider Instances
+
+You can define multiple instances of the same provider in order to support
+multiple regions, multiple hosts, etc. The primary use case for this for
+multiple cloud regions. Other use cases including targeting multiple
+Docker hosts, multiple Consul hosts, etc.
+
+To define multiple provider instances, repeat the provider configuration
+multiple times, but set the `alias` field and name the provider. For
+example:
+
+```
+# The default provider
+provider "aws" {
+	# ...
+}
+
+# West coast region
+provider "aws" {
+	alias = "west"
+
+	region = "us-west-2"
+}
+```
+
+After naming a provider, you reference it in resources with the `provider`
+field:
+
+```
+resource "aws_instance" "foo" {
+	provider = "aws.west"
+
+	# ...
+}
+```
+
+If a provider isn't specified, then the default provider configuration
+is used (the provider configuration with no `alias` set). The value of the
+`provider` field is `TYPE.ALIAS`, such as "aws.west" above.
+
 ## Syntax
 
 The full syntax is:
@@ -64,6 +104,7 @@ The full syntax is:
 ```
 provider NAME {
 	CONFIG ...
+	[alias = ALIAS]
 }
 ```
 

website/source/docs/configuration/resources.html.md

@@ -127,6 +127,32 @@ resource "aws_instance" "app" {
 }
 ```
 
+## Multiple Provider Instances
+
+By default, a resource targets the resource based on its type. For example
+an `aws_instance` resource will target the "aws" provider. As of Terraform
+0.5.0, a resource can target any provider by name.
+
+The primary use case for this is to target a specific configuration of
+a provider that is configured multiple times to support multiple regions, etc.
+
+To target another provider, set the `provider` field:
+
+```
+resource "aws_instance" "foo" {
+	provider = "aws.west"
+
+	# ...
+}
+```
+
+The value of the field should be `TYPE` or `TYPE.ALIAS`. The `ALIAS` value
+comes from the `alias` field value when configuring the
+[provider](/docs/configuration/providers.html).
+
+If no `provider` field is specified, the default (provider with no alias)
+provider is used.
+
 ## Syntax
 
 The full syntax is:
@@ -135,7 +161,9 @@ The full syntax is:
 resource TYPE NAME {
 	CONFIG ...
 	[count = COUNT]
-    [depends_on = [RESOURCE NAME, ...]]
+	[depends_on = [RESOURCE NAME, ...]]
+	[provider = PROVIDER]
+
     [LIFECYCLE]
 
 	[CONNECTION]