IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update website/docs/language/data-sources (#224)

Browse Source 
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń 2023-08-29 16:37:38 +02:00 committed by GitHub
parent 0a37fade1f
commit bf5e6c079d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
website/docs/language/data-sources/index.mdx
View File

@ -1,20 +1,18 @@
---
page_title: Data Sources - Configuration Language
description: >-
Data sources allow Terraform to use external data, function output, and data
Data sources allow OpenTF to use external data, function output, and data
from other configurations. Learn data resource arguments, behavior, and
lifecycle.
---
# Data Sources
_Data sources_ allow Terraform to use information defined outside of Terraform,
defined by another separate Terraform configuration, or modified by functions.
_Data sources_ allow OpenTF to use information defined outside of OpenTF,
defined by another separate OpenTF configuration, or modified by functions.
> **Hands-on:** Try the [Query Data Sources](/terraform/tutorials/configuration-language/data-sources) tutorial.
Each [provider](/terraform/language/providers) may offer data sources
alongside its set of [resource](/terraform/language/resources)
Each [provider](/opentf/language/providers) may offer data sources
alongside its set of [resource](/opentf/language/resources)
types.
## Using Data Sources
@ -34,9 +32,9 @@ data "aws_ami" "example" {
}
```
A `data` block requests that Terraform read from a given data source ("aws_ami")
A `data` block requests that OpenTF 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
to refer to this resource from elsewhere in the same OpenTF 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
@ -50,8 +48,8 @@ all arguments defined specifically for [the `aws_ami` data source](https://regis
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 cause OpenTF to create, update, and delete infrastructure
objects, data resources cause OpenTF only to _read_ objects. For brevity,
managed resources are often referred to just as "resources" when the meaning
is clear from context.
@ -61,29 +59,29 @@ 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](/terraform/language/providers),
which is a plugin for Terraform that offers a collection of resource types and
Each data source in turn belongs to a [provider](/opentf/language/providers),
which is a plugin for OpenTF 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](/terraform/language/expressions) and other dynamic
Terraform language features.
use of [expressions](/opentf/language/expressions) and other dynamic
OpenTF language features.
However, there are some "meta-arguments" that are defined by Terraform itself
However, there are some "meta-arguments" that are defined by OpenTF 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
Terraform reads data resources during the planning phase when possible, but
OpenTF reads data resources during the planning phase when possible, but
announces in the plan when it must defer reading resources until the apply
phase to preserve the order of operations. Terraform defers reading data
phase to preserve the order of operations. OpenTF defers reading data
resources in the following situations:
* At least one of the given arguments is a managed resource attribute or
other value that Terraform cannot predict until the apply step.
other value that OpenTF cannot predict until the apply step.
* The data resource depends directly on a managed resource that itself has
planned changes in the current plan.
* The data resource has
@ -100,7 +98,7 @@ be used in situations where values must be fully known.
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
only within OpenTF itself, calculating some results and exposing them
for use elsewhere.
For example, local-only data sources exist for
@ -109,13 +107,13 @@ For example, local-only data sources exist for
[rendering AWS IAM policies](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document).
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
sources, but their result data exists only temporarily during a OpenTF
operation, and is re-calculated each time a new plan is created.
## Data Resource Dependencies
Data resources have the same dependency resolution behavior
[as defined for managed resources](/terraform/language/resources/behavior#resource-dependencies).
[as defined for managed resources](/opentf/language/resources/behavior#resource-dependencies).
Setting the `depends_on` meta-argument within `data` blocks defers reading of
the data source until after all changes to the dependencies have been applied.
@ -127,8 +125,6 @@ referencing the managed resource values through a `local` value, unless the
data resource itself has
[custom conditions](#custom-condition-checks).
~> **NOTE:** **In Terraform 0.12 and earlier**, 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.
## Custom Condition Checks
You can use `precondition` and `postcondition` blocks to specify assumptions and guarantees about how the data source operates. The following examples creates a postcondition that checks whether the AMI has the correct tags.
@ -149,13 +145,13 @@ data "aws_ami" "example" {
Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations.
Refer to [Custom Condition Checks](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
## Multiple Resource Instances
Data resources support [`count`](/terraform/language/meta-arguments/count)
and [`for_each`](/terraform/language/meta-arguments/for_each)
Data resources support [`count`](/opentf/language/meta-arguments/count)
and [`for_each`](/opentf/language/meta-arguments/for_each)
meta-arguments as defined for managed resources, with the same syntax and behavior.
As with managed resources, when `count` or `for_each` is present it is important to
@ -165,7 +161,7 @@ own variant of the constraint arguments, producing an indexed result.
## Selecting a Non-default Provider Configuration
Data resources support [the `provider` meta-argument](/terraform/language/meta-arguments/resource-provider)
Data resources support [the `provider` meta-argument](/opentf/language/meta-arguments/resource-provider)
as defined for managed resources, with the same syntax and behavior.
## Lifecycle Customizations
@ -202,8 +198,8 @@ and name must be unique.
Within the block (the `{ }`) is configuration for the data instance. The
configuration is dependent on the type; as with
[resources](/terraform/language/resources), each provider on the
[Terraform Registry](https://registry.terraform.io/browse/providers) has its own
[resources](/opentf/language/resources), each provider on the
[Provider Registry](https://registry.terraform.io/browse/providers) has its own
documentation for configuring and using the data types it provides.
Each data instance will export one or more attributes, which can be
@ -220,13 +216,13 @@ resource "aws_instance" "web" {
## Meta-Arguments
As data sources are essentially a read only subset of resources, they also
support the same [meta-arguments](/terraform/language/resources/syntax#meta-arguments) of resources
support the same [meta-arguments](/opentf/language/resources/syntax#meta-arguments) of resources
with the exception of the
[`lifecycle` configuration block](/terraform/language/meta-arguments/lifecycle).
[`lifecycle` configuration block](/opentf/language/meta-arguments/lifecycle).
### Non-Default Provider Configurations
Similarly to [resources](/terraform/language/resources), when
Similarly to [resources](/opentf/language/resources), when
a module has multiple configurations for the same provider you can specify which
configuration to use with the `provider` meta-argument:
@ -239,14 +235,14 @@ data "aws_ami" "web" {
```
See
[The Resource `provider` Meta-Argument](/terraform/language/meta-arguments/resource-provider)
[The Resource `provider` Meta-Argument](/opentf/language/meta-arguments/resource-provider)
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"
data instance will be read and its state updated during OpenTF'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.