From 64f2651204c837532ec6abbdb79de9959954cce6 Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Sun, 1 May 2016 16:41:16 -0700
Subject: [PATCH] website: Initial documentation about data sources

This will undoubtedly evolve as implementation continues, but this is some
initial documentation based on the design doc.
---
 .../docs/configuration/data-sources.html.md   | 103 ++++++++++++++++++
 website/source/layouts/docs.erb               |   4 +
 2 files changed, 107 insertions(+)
 create mode 100644 website/source/docs/configuration/data-sources.html.md

diff --git a/website/source/docs/configuration/data-sources.html.md b/website/source/docs/configuration/data-sources.html.md
new file mode 100644
index 0000000000..a99a3ad4a7
--- /dev/null
+++ b/website/source/docs/configuration/data-sources.html.md
@@ -0,0 +1,103 @@
+---
+layout: "docs"
+page_title: "Configuring Data Sources"
+sidebar_current: "docs-config-data-sources"
+description: |-
+  Data sources allow data to be fetched or computed for use elsewhere in Terraform configuration.
+---
+
+# Data Source Configuration
+
+*Data sources* allow data to be fetched or computed for use elsewhere
+in Terraform configuration. Use of data sources allows a Terraform
+configuration to build on information defined outside of Terraform,
+or defined by another separate Terraform configuration.
+
+[Providers](/docs/configuration/providers.html) are responsible in
+Terraform for defining and implementing data sources. Whereas
+a [resource](/docs/configuration/resource.html) causes Terraform
+to create and manage a new infrastructure component, data sources
+present read-only views into pre-existing data, or they compute
+new values on the fly within Terraform itself.
+
+For example, a data source may retrieve artifact information from
+Atlas, configuration information from Consul, or look up a pre-existing
+AWS resource by filtering on its attributes and tags.
+
+Every data source in Terraform is mapped to a provider based
+on longest-prefix matching. For example the `aws_ami`
+data source would map to the `aws` provider (if that exists).
+
+This page assumes you're familiar with the
+[configuration syntax](/docs/configuration/syntax.html)
+already.
+
+## Example
+
+A data source configuration looks like the following:
+
+```
+// Find the latest available AMI that is tagged with Component = web
+data "aws_ami" "web" {
+  state = "available"
+  tags = {
+    Component = "web"
+  }
+  select = "latest"
+}
+```
+
+## Description
+
+The `data` block creates a data instance of the given `TYPE` (first
+parameter) and `NAME` (second parameter). The combination of the type
+and name must be unique.
+
+Within the block (the `{ }`) is configuration for the data instance. The
+configuration is dependent on the type, and is documented for each
+data source in the [providers section](/docs/providers/index.html).
+
+Each data instance will export one or more attributes, which can be
+interpolated into other resources using variables of the form
+`data.TYPE.NAME.ATTR`. For example:
+
+```
+resource "aws_instance" "web" {
+    ami = "${data.aws_ami.web.id}"
+    instance_type = "t1.micro"
+}
+```
+
+## Multiple Provider Instances
+
+Similarly to [resources](/docs/configuration/resource.html), the
+`provider` meta-parameter can be used where a configuration has
+multiple aliased instances of the same provider:
+
+```
+data "aws_ami" "web" {
+  provider = "aws.west"
+
+  // etc...
+}
+
+```
+
+See the "Multiple Provider Instances" documentation for resources
+for more information.
+
+## Data Source Lifecycle
+
+If the arguments of a data instance contain no references to computed values,
+such as attributes of resources that have not yet been created, then the
+data instance will be read and its state updated during Terraform's "refresh"
+phase, which by default runs prior to creating a plan. This ensures that the
+retrieved data is available for use during planning and the diff will show
+the real values obtained.
+
+Data instance arguments may refer to computed values, in which case the
+attributes of the instance itself cannot be resolved until all of its
+arguments are defined. In this case, refreshing the data instance will be
+deferred until the "apply" phase, and all interpolations of the data instance
+attributes will show as "computed" in the plan since the values are not yet
+known.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index bb94f405ba..7bca0707db 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -29,6 +29,10 @@
 					<a href="/docs/configuration/resources.html">Resources</a>
 					</li>
 
+					<li<%= sidebar_current("docs-config-data-sources") %>>
+					<a href="/docs/configuration/data-sources.html">Data Sources</a>
+					</li>
+
 					<li<%= sidebar_current("docs-config-providers") %>>
 					<a href="/docs/configuration/providers.html">Providers</a>
 					</li>