website: Revise the "Data Sources" configuration docs section
This adopts a more guide-like writing style, similar to what prior commits have done to some other subsections of this section. The data sources page has not got any real attention since the feature was first added, and our vocabulary for describing them and their lifecycle hadn't quite settled when the page was originally written. This new version is consistent in how it uses "data source" to describe the feature that providers offer and "data resource" to describe what is created by a "data" block in configuration, which then allows us to draw on the many shared features between both data and managed resources. For the moment this waits until "data resource" is defined in order to first introduce the qualifier "managed resource". We may wish to revise this again to mention that more specific nomenclature in passing on the "Resources" page, in case a user encounters it elsewhere and wants to learn what it means without needing to be familiar with data resources first.
This commit is contained in:
Martin Atkins
parent
eeb96b1e12
commit
e1754970a8
|
|
@ -6,31 +6,143 @@ description: |-
|
|||
Data sources allow data to be fetched or computed for use elsewhere in Terraform configuration.
|
||||
---
|
||||
|
||||
# Data Source Configuration
|
||||
# Data Sources
|
||||
|
||||
*Data sources* allow data to be fetched or computed for use elsewhere
|
||||
_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,
|
||||
configuration to make use of 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/resources.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.
|
||||
Each [provider](/docs/configuration/providers.html) make offer data sources
|
||||
alongside its set of [resource types](/docs/configuration/resources.html#resource-types-and-arguments).
|
||||
|
||||
For example, a data source may retrieve artifact information from
|
||||
Terraform Enterprise, configuration information from Consul, or look up a pre-existing
|
||||
AWS resource by filtering on its attributes and tags.
|
||||
## Using Data Sources
|
||||
|
||||
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).
|
||||
A data source is accessed via a special kind of resource known as a
|
||||
_data resource_, declared using a `data` block:
|
||||
|
||||
This page assumes you're familiar with the
|
||||
[configuration syntax](/docs/configuration/syntax.html)
|
||||
already.
|
||||
```hcl
|
||||
data "aws_ami" "example" {
|
||||
most_recent = true
|
||||
|
||||
owners = ["self"]
|
||||
tags = {
|
||||
Name = "app-server"
|
||||
Tested = "true"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A `data` block requests that Terraform read from a given data source ("aws_ami")
|
||||
and export the result under the given local name ("example"). The name is used
|
||||
to refer to this resource from elsewhere in the same Terraform module, but has
|
||||
no significance outside of the scope of a module.
|
||||
|
||||
The data source and name together serve as an identifier for a given
|
||||
resource and so must be unique within a module.
|
||||
|
||||
Within the block body (between `{` and `}`) are query constraints defined by
|
||||
the data source. Most arguments in this section depend on the
|
||||
data source, and indeed in this example `most_recent`, `owners` and `tags` are
|
||||
all arguments defined specifically for [the `aws_ami` data source](/docs/providers/aws/d/ami.html).
|
||||
|
||||
When distinguishing from data resources, the primary kind of resource (as declared
|
||||
by a `resource` block) is known as a _managed resource_. Both kinds of resources
|
||||
take arguments and export attributes for use in configuration, but while
|
||||
managed resources cause Terraform to create, update, and delete infrastructure
|
||||
objects, data resources cause Terraform only to _read_ objects. For brevity,
|
||||
managed resources are often referred to just as "resources" when the meaning
|
||||
is clear from context.
|
||||
|
||||
## Data Source Arguments
|
||||
|
||||
Each data resource is associated with a single data source, which determines
|
||||
the kind of object (or objects) it reads and what query constraint arguments
|
||||
are available.
|
||||
|
||||
Each data source in turn belongs to a [provider](/docs/configuration/providers.html),
|
||||
which is a plugin for Terraform that offers a collection of resource types and
|
||||
data sources that most often belong to a single cloud or on-premises
|
||||
infrastructure platform.
|
||||
|
||||
Most of the items within the body of a `data` block are defined by and
|
||||
specific to the selected data source, and these arguments can make full
|
||||
use of [expressions](/docs/configuration/expressions.html) and other dynamic
|
||||
Terraform language features.
|
||||
|
||||
However, there are some "meta-arguments" that are defined by Terraform itself
|
||||
and apply across all data sources. These arguments often have additional
|
||||
restrictions on what language features can be used with them, and are described
|
||||
in more detail in the following sections.
|
||||
|
||||
## Data Resource Behavior
|
||||
|
||||
If the query constraint arguments for a data resource refer only to constant
|
||||
values or values that are already known, the data resource will be read and its
|
||||
state updated during Terraform's "refresh" phase, which runs prior to creating a plan.
|
||||
This ensures that the retrieved data is available for use during planning and
|
||||
so Terraform's plan will show the actual values obtained.
|
||||
|
||||
Query constraint arguments may refer to values that cannot be determined until
|
||||
after configuration is applied, such as the id of a managed resource that has
|
||||
not been created yet. In this case, reading from the data source is deferred
|
||||
until the apply phase, and any references to the results of the data resource
|
||||
elsewhere in configuration will themselves be unknown until after the
|
||||
configuration has been applied.
|
||||
|
||||
## Local-only Data Sources
|
||||
|
||||
While many data sources correspond to an infrastructure object type that
|
||||
is accessed via a remote network API, some specialized data sources operate
|
||||
only within Terraform itself, calculating some results and exposing them
|
||||
for use elsewhere.
|
||||
|
||||
For example, local-only data sources exist for
|
||||
[rendering templates](/docs/providers/template/d/template_file.html),
|
||||
[reading local files](/docs/providers/local/d/file.html), and
|
||||
[rendering AWS IAM policies](/docs/providers/aws/d/iam_policy_document.html).
|
||||
|
||||
The behavior of local-only data sources is the same as all other data
|
||||
sources, but their result data exists only temporarily during a Terraform
|
||||
operation, and is re-calulated each time a new plan is created.
|
||||
|
||||
## Data Resource Dependencies
|
||||
|
||||
Data resources have the same dependency resolution behavior
|
||||
[as defined for managed resources](/docs/configuration/resources.html#resource-dependencies).
|
||||
|
||||
In particular, the `depends_on` meta-argument is also available within `data`
|
||||
blocks, with the same meaning and syntax as in `resource` blocks.
|
||||
|
||||
However, due to the data resource behavior of deferring the read until the
|
||||
apply phase when depending on values that are not yet known, using `depends_on`
|
||||
with data resources will force the read to _always_ be deferred to the apply
|
||||
phase, and therefore a configuration that uses `depends_on` with a data
|
||||
resource can never converge.
|
||||
|
||||
Due to this behavior, we do not recommend using `depends_on` with data
|
||||
resources.
|
||||
|
||||
## Multiple Resource Instances
|
||||
|
||||
Data resources support [the `count` meta-argument](/docs/configuration/resources.html#multiple-resource-instances)
|
||||
as defined for managed resources, with the same syntax and behavior.
|
||||
|
||||
As with managed resources, when `count` is present it is important to
|
||||
distinguish the resource itself from the multiple resource _instances_ it
|
||||
creates. Each instance will separately read from its data source with its
|
||||
own variant of the constraint arguments, producing an indexed result.
|
||||
|
||||
## Selecting a Non-default Provider Configuration
|
||||
|
||||
Data resources support [the `providers` meta-argument](/docs/configuration/resources.html#selecting-a-non-default-provider-configuration)
|
||||
as defined for managed resources, with the same syntax and behavior.
|
||||
|
||||
## Lifecycle Customizations
|
||||
|
||||
Data resources do not currently have any customization settings available
|
||||
for their lifecycle, but the `lifecycle` nested block is reserved in case
|
||||
any are added in future versions.
|
||||
|
||||
## Example
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue