github.com/loicalbertin/terraform@v0.6.15-0.20170626182346-8e2583055467/website/docs/configuration/data-sources.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Configuring Data Sources"
     4  sidebar_current: "docs-config-data-sources"
     5  description: |-
     6    Data sources allow data to be fetched or computed for use elsewhere in Terraform configuration.
     7  ---
     8  
     9  # Data Source Configuration
    10  
    11  *Data sources* allow data to be fetched or computed for use elsewhere
    12  in Terraform configuration. Use of data sources allows a Terraform
    13  configuration to build on information defined outside of Terraform,
    14  or defined by another separate Terraform configuration.
    15  
    16  [Providers](/docs/configuration/providers.html) are responsible in
    17  Terraform for defining and implementing data sources. Whereas
    18  a [resource](/docs/configuration/resources.html) causes Terraform
    19  to create and manage a new infrastructure component, data sources
    20  present read-only views into pre-existing data, or they compute
    21  new values on the fly within Terraform itself.
    22  
    23  For example, a data source may retrieve artifact information from
    24  Terraform Enterprise, configuration information from Consul, or look up a pre-existing
    25  AWS resource by filtering on its attributes and tags.
    26  
    27  Every data source in Terraform is mapped to a provider based
    28  on longest-prefix matching. For example the `aws_ami`
    29  data source would map to the `aws` provider (if that exists).
    30  
    31  This page assumes you're familiar with the
    32  [configuration syntax](/docs/configuration/syntax.html)
    33  already.
    34  
    35  ## Example
    36  
    37  A data source configuration looks like the following:
    38  
    39  ```hcl
    40  # Find the latest available AMI that is tagged with Component = web
    41  data "aws_ami" "web" {
    42    filter {
    43      name   = "state"
    44      values = ["available"]
    45    }
    46  
    47    filter {
    48      name   = "tag:Component"
    49      values = ["web"]
    50    }
    51  
    52    most_recent = true
    53  }
    54  ```
    55  
    56  ## Description
    57  
    58  The `data` block creates a data instance of the given `TYPE` (first
    59  parameter) and `NAME` (second parameter). The combination of the type
    60  and name must be unique.
    61  
    62  Within the block (the `{ }`) is configuration for the data instance. The
    63  configuration is dependent on the type, and is documented for each
    64  data source in the [providers section](/docs/providers/index.html).
    65  
    66  Each data instance will export one or more attributes, which can be
    67  interpolated into other resources using variables of the form
    68  `data.TYPE.NAME.ATTR`. For example:
    69  
    70  ```hcl
    71  resource "aws_instance" "web" {
    72    ami           = "${data.aws_ami.web.id}"
    73    instance_type = "t1.micro"
    74  }
    75  ```
    76  
    77  ### Meta-parameters
    78  
    79  As data sources are essentially a read only subset of resources they also support the same [meta-parameters](https://www.terraform.io/docs/configuration/resources.html#meta-parameters) of resources except for the [`lifecycle` configuration block](https://www.terraform.io/docs/configuration/resources.html#lifecycle).
    80  
    81  ## Multiple Provider Instances
    82  
    83  Similarly to [resources](/docs/configuration/resources.html), the
    84  `provider` meta-parameter can be used where a configuration has
    85  multiple aliased instances of the same provider:
    86  
    87  ```hcl
    88  data "aws_ami" "web" {
    89    provider = "aws.west"
    90  
    91    # ...
    92  }
    93  ```
    94  
    95  See the ["Multiple Provider Instances"](/docs/configuration/resources.html#multiple-provider-instances) documentation for resources
    96  for more information.
    97  
    98  ## Data Source Lifecycle
    99  
   100  If the arguments of a data instance contain no references to computed values,
   101  such as attributes of resources that have not yet been created, then the
   102  data instance will be read and its state updated during Terraform's "refresh"
   103  phase, which by default runs prior to creating a plan. This ensures that the
   104  retrieved data is available for use during planning and the diff will show
   105  the real values obtained.
   106  
   107  Data instance arguments may refer to computed values, in which case the
   108  attributes of the instance itself cannot be resolved until all of its
   109  arguments are defined. In this case, refreshing the data instance will be
   110  deferred until the "apply" phase, and all interpolations of the data instance
   111  attributes will show as "computed" in the plan since the values are not yet
   112  known.