github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/providers/consul/r/prepared_query.markdown (about)

     1  ---
     2  layout: "consul"
     3  page_title: "Consul: consul_prepared_query"
     4  sidebar_current: "docs-consul-resource-prepared-query"
     5  description: |-
     6    Allows Terraform to manage a Consul prepared query
     7  ---
     8  
     9  # consul_prepared_query
    10  
    11  Allows Terraform to manage a Consul prepared query.
    12  
    13  Managing prepared queries is done using Consul's REST API. This resource is
    14  useful to provide a consistent and declarative way of managing prepared
    15  queries in your Consul cluster using Terraform.
    16  
    17  ## Example Usage
    18  
    19  ```hcl
    20  # Creates a prepared query myquery.query.consul that finds the nearest
    21  # healthy myapp.service.consul instance that has the active tag and not
    22  # the standby tag.
    23  resource "consul_prepared_query" "myapp-query" {
    24    name         = "myquery"
    25    datacenter   = "us-central1"
    26    token        = "abcd"
    27    stored_token = "wxyz"
    28    only_passing = true
    29    near         = "_agent"
    30  
    31    service = "myapp"
    32    tags    = ["active", "!standby"]
    33  
    34    failover {
    35      nearest_n   = 3
    36      datacenters = ["us-west1", "us-east-2", "asia-east1"]
    37    }
    38  
    39    dns {
    40      ttl = "30s"
    41    }
    42  }
    43  
    44  # Creates a Prepared Query Template that matches *-near-self.query.consul
    45  # and finds the nearest service that matches the glob character (e.g.
    46  # foo-near-self.query.consul will find the nearest healthy foo.service.consul).
    47  resource "consul_prepared_query" "service-near-self" {
    48    datacenter   = "nyc1"
    49    token        = "abcd"
    50    stored_token = "wxyz"
    51    name         = ""
    52    only_passing = true
    53    near         = "_agent"
    54  
    55    template {
    56      type   = "name_prefix_match"
    57      regexp = "^(.*)-near-self$"
    58    }
    59  
    60    service = "$${match(1)}"
    61  
    62    failover {
    63      nearest_n   = 3
    64      datacenters = ["dc2", "dc3", "dc4"]
    65    }
    66  
    67    dns {
    68      ttl = "5m"
    69    }
    70  }
    71  ```
    72  
    73  ## Argument Reference
    74  
    75  The following arguments are supported:
    76  
    77  * `datacenter` - (Optional) The datacenter to use. This overrides the
    78    datacenter in the provider setup and the agent's default datacenter.
    79  
    80  * `token` - (Optional) The ACL token to use when saving the prepared query.
    81    This overrides the token that the agent provides by default.
    82  
    83  * `stored_token` - (Optional) The ACL token to store with the prepared
    84    query. This token will be used by default whenever the query is executed.
    85  
    86  * `name` - (Required) The name of the prepared query. Used to identify
    87    the prepared query during requests. Can be specified as an empty string
    88    to configure the query as a catch-all.
    89  
    90  * `service` - (Required) The name of the service to query.
    91  
    92  * `session` - (Optional) The name of the Consul session to tie this query's
    93    lifetime to.  This is an advanced parameter that should not be used without a
    94    complete understanding of Consul sessions and the implications of their use
    95    (it is recommended to leave this blank in nearly all cases).  If this
    96    parameter is omitted the query will not expire.
    97  
    98  * `tags` - (Optional) The list of required and/or disallowed tags.  If a tag is
    99    in this list it must be present.  If the tag is preceded with a "!" then it is
   100    disallowed.
   101  
   102  * `only_passing` - (Optional) When `true`, the prepared query will only
   103    return nodes with passing health checks in the result.
   104  
   105  * `near` - (Optional) Allows specifying the name of a node to sort results
   106    near using Consul's distance sorting and network coordinates. The magic
   107    `_agent` value can be used to always sort nearest the node servicing the
   108    request.
   109  
   110  * `failover` - (Optional) Options for controlling behavior when no healthy
   111    nodes are available in the local DC.
   112  
   113    * `nearest_n` - (Optional) Return results from this many datacenters,
   114      sorted in ascending order of estimated RTT.
   115  
   116    * `datacenters` - (Optional) Remote datacenters to return results from.
   117  
   118  * `dns` - (Optional) Settings for controlling the DNS response details.
   119  
   120    * `ttl` - (Optional) The TTL to send when returning DNS results.
   121  
   122  * `template` - (Optional) Query templating options. This is used to make a
   123    single prepared query respond to many different requests.
   124  
   125    * `type` - (Required) The type of template matching to perform. Currently
   126      only `name_prefix_match` is supported.
   127  
   128    * `regexp` - (Required) The regular expression to match with. When using
   129      `name_prefix_match`, this regex is applied against the query name.
   130  
   131  ## Attributes Reference
   132  
   133  The following attributes are exported:
   134  
   135  * `id` - The ID of the prepared query, generated by Consul.