luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Adds basic docs for prepared query templates.

This commit is contained in:
James Phillips 2016-03-02 21:56:03 -08:00
parent 3c512fc089
commit e6232a21e4
2 changed files with 103 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
website/source/docs/agent/dns.html.markdown
View File

@ -187,7 +187,10 @@ The `query or name` is the ID or given name of an existing
[Prepared Query](/docs/agent/http/query.html). These behave like standard service
queries but provide a much richer set of features, such as filtering by multiple
tags and automatically failing over to look for services in remote datacenters if
no healthy nodes are available in the local datacenter.
no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also
added support for [prepared query templates](/docs/agent/http/query.html#templates)
which can match names using a prefix match, allowing one template to apply to
potentially many services.
To allow for simple load balancing, the set of nodes returned is randomized each time.
Both A and SRV records are supported. SRV records provide the port that a service is

102
website/source/docs/agent/http/query.html.markdown
View File

@ -17,6 +17,15 @@ service. This is particularly useful in combination with Consul's
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than
would be possible given the limited entry points exposed by DNS.
Consul 0.6.4 and later also supports prepared query templates. Templates are
defined in a similar way to regular prepared queries but instead of applying to
just a single query name, they can respond to names starting with a configured
prefix. The service name being queried is computed using the matched prefix
and/or a regular expression. This provides a powerful tool that lets you apply
the features of prepared queries to a range (or potentially all) services with a
small number of templates. Details about prepared query templates are covered
[below](#templates).
The following endpoints are supported:
* [`/v1/query`](#general): Creates a new prepared query or lists
@ -51,8 +60,8 @@ provided using the "?dc=" query parameter.
If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges for the `Name` of the query being created.
The create operation expects a JSON request body that defines the prepared query,
like this example:
The create operation expects a JSON request body that defines the prepared
query, like this example:
```javascript
{
@ -157,6 +166,92 @@ a JSON body:
}
```
<a name="templates"><b>Prepared Query Templates</b></a>
Consul 0.6.4 and later also support prepared query templates. These are created similar
to static templates, except with some additional fields and features. Here's an example:
```javascript
{
"Name": "geo-db",
"Template" {
"Type": "name_prefix_match",
"Regexp": "^geo-db-(.*?)-([^\-]+?)$"
},
"Service": {
"Service": "mysql-${regexp.match(1)}",
"Failover": {
"NearestN": 3,
"Datacenters": ["dc1", "dc2"]
},
"OnlyPassing": true,
"Tags": ["${regexp.match(2)}"]
}
}
```
The new `Template` structure configures a prepared query as a template instead of a
static query. It has two fields:
`Type` is the query type, which must be "name_prefix_match". This means that the
template will apply to any query lookup with a name whose prefix matches the `Name`
field of the template. In this example, any query for "geo-db" will match this
query. Query templates are resolved using a longest prefix match, so it's possible
to have high-level templates that are overridden for specific services. Static
queries are always resolved first, so they can also override templates.
`Regexp` is an optional regular expression which is used to extract fields from the
entire name, once this template is selected. In this example, the regular expression
takes the first item after the "-" as the database name and everything else after as
a tag. See the [RE2](https://github.com/google/re2/wiki/Syntax) reference for syntax
of this regular expression.
All other fields of the query have the same meanings as for a static query, except
that several interpolation variables are available to dynamically populate the query
before it is executed. All of the string fields inside the `Service` structure are
interpolated, with the following variables available:
`${name.full}` has the entire name that was queried. For example, a lookup for
"geo-db-customer-master.consul" in the example above would set this variable to
"geo-db-customer-master".
`${name.prefix}` has the prefix that matched. This would always be "geo-db" for
the example above.
`${name.suffix}` has the suffix after the prefix. For example, a lookup for
"geo-db-customer-master.consul" in the example above would set this variable to
"-customer-master".
`${match(N)}` returns the regular expression match at the given index N. The
0 index will have the entire match, and >0 will have the results of each match
group. For example, a lookup for "geo-db-customer-master.consul" in the example
above with a `Regexp` field set to `^geo-db-(.*?)-([^\-]+?)$` would return
"geo-db-customer-master" for `${match(0)}`, "customer" for `${match(1)}`, and
"master" for `${match(2)}`. If the regular expression doesn't match, or an invalid
index is given, then `${match(N)}` will return an empty string.
Using templates it's possible to apply prepared query behaviors to many services
with a single template. Here's an example template that matches any query and
applies a failover policy to it:
```javascript
{
"Name": "",
"Template" {
"Type": "name_prefix_match",
},
"Service": {
"Service": "${name.full}",
"Failover": {
"NearestN": 3,
}
}
}
```
This will match any lookup for `*.query.consul` and will attempt to find the
service locally, and otherwise attempt to find that service in the next three
closest datacenters.
#### GET Method
When using the GET method, Consul will provide a listing of all prepared queries.
@ -253,7 +348,8 @@ If the API call succeeds, a 200 status code is returned.
The query execute endpoint supports only the `GET` method and is used to
execute a prepared query. The \<query or name\> argument is the ID or name
of an existing prepared query.
of an existing prepared query, or a name that matches a prefix name for a
[prepared query template](#templates).
By default, the datacenter of the agent is queried; however, the `dc` can be
provided using the "?dc=" query parameter. This endpoint does not support