mirror of https://github.com/hashicorp/consul
Cleans up the documents.
James Phillips
parent
7d392118d2
commit
dca480e284
|
|
@ -15,7 +15,7 @@ Prepared queries allow you to register a complex service query and then execute
|
|||
it later via its ID or name to get a set of healthy nodes that provide a given
|
||||
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 syntax DNS provides.
|
||||
would be possible given the limited entry points exposed by DNS.
|
||||
|
||||
The following endpoints are supported:
|
||||
|
||||
|
|
@ -45,12 +45,11 @@ The general query endpoint supports the `POST` and `GET` methods.
|
|||
When using the `POST` method, Consul will create a new prepared query and return
|
||||
its ID if it is created successfully.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
By default, the datacenter of the agent is queried; however, the `dc` can be
|
||||
provided using the "?dc=" query parameter.
|
||||
|
||||
If ACLs are enabled, then the client will need to supply a token with `query`
|
||||
write privileges sufficient to match the service name being queried and the `Name`
|
||||
given to the query, if any. See also the note about the `Token` field below.
|
||||
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:
|
||||
|
|
@ -86,12 +85,13 @@ given session is invalidated. This is optional, and if not given the prepared
|
|||
query must be manually removed when no longer needed.
|
||||
|
||||
<a name="token"></a>
|
||||
`Token` is a captured ACL Token to use when the query is executed. This allows
|
||||
queries to be executed by clients with lesser or even no ACL Token, so this
|
||||
should be used with care. The token itself can only be seen by clients with a
|
||||
management token. If the `Token` field is left blank, the client's ACL Token
|
||||
will be used to determine if they have access to the service being queried. If
|
||||
the client does not supply an ACL Token, the anonymous token will be used.
|
||||
`Token`, if specified, is a captured ACL Token that is reused as the ACL Token
|
||||
every time the query is executed. This allows queries to be executed by clients
|
||||
with lesser or even no ACL Token, so this should be used with care. The token
|
||||
itself can only be seen by clients with a management token. If the `Token`
|
||||
field is left blank or omitted, the client's ACL Token will be used to determine
|
||||
if they have access to the service being queried. If the client does not supply
|
||||
an ACL Token, the anonymous token will be used.
|
||||
|
||||
Note that Consul version 0.6.3 and earlier would automatically capture the ACL
|
||||
Token for use in the future when prepared queries were executed and would
|
||||
|
|
@ -161,7 +161,7 @@ a JSON body:
|
|||
|
||||
When using the GET method, Consul will provide a listing of all prepared queries.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
By default, the datacenter of the agent is queried; however, the `dc` can be
|
||||
provided using the "?dc=" query parameter. This endpoint supports blocking
|
||||
queries and all consistency modes.
|
||||
|
||||
|
|
@ -208,12 +208,11 @@ The query-specific endpoint supports the `GET`, `PUT`, and `DELETE` methods. The
|
|||
|
||||
The `PUT` method allows an existing prepared query to be updated.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
By default, the datacenter of the agent is queried; however, the `dc` can be
|
||||
provided using the "?dc=" query parameter.
|
||||
|
||||
If ACLs are enabled, then the client will need to supply a token with `query`
|
||||
write privileges sufficient to match the service name being queried and the `Name`
|
||||
given to the query, if any.
|
||||
If ACLs are enabled, the client will need to supply an ACL Token with `query`
|
||||
write privileges for the `Name` of the query being updated.
|
||||
|
||||
The body is the same as is used to create a prepared query, as described above.
|
||||
|
||||
|
|
@ -223,7 +222,7 @@ If the API call succeeds, a 200 status code is returned.
|
|||
|
||||
The `GET` method allows an existing prepared query to be fetched.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
By default, the datacenter of the agent is queried; however, the `dc` can be
|
||||
provided using the "?dc=" query parameter. This endpoint supports blocking
|
||||
queries and all consistency modes.
|
||||
|
||||
|
|
@ -240,12 +239,11 @@ management token is used.
|
|||
|
||||
The `DELETE` method is used to delete a prepared query.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
By default, the datacenter of the agent is queried; however, the `dc` can be
|
||||
provided using the "?dc=" query parameter.
|
||||
|
||||
If ACLs are enabled, then the client will need to supply a token with `query`
|
||||
write privileges sufficient to match the service name being queried and the `Name`
|
||||
given to the query, if any.
|
||||
If ACLs are enabled, the client will need to supply an ACL Token with `query`
|
||||
write privileges for the `Name` of the query being deleted.
|
||||
|
||||
No body is required as part of this request.
|
||||
|
||||
|
|
@ -257,7 +255,7 @@ 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.
|
||||
|
||||
By default, the datacenter of the agent is queried; however, the dc can be
|
||||
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
|
||||
blocking queries, but it does support all consistency modes.
|
||||
|
||||
|
|
|
|||
|
|
@ -348,11 +348,6 @@ service, then the DNS interface will return no records when queried for it.
|
|||
<a name="prepared_query_acls"></a>
|
||||
## Prepared Query ACLs
|
||||
|
||||
Prepared queries have a more complicated relationship with ACLs than most other
|
||||
Consul resources because they have a lifecycle related to creating, reading,
|
||||
updating, and deleting queries, and then a separate lifecycle related to
|
||||
executing queries.
|
||||
|
||||
As we've gotten feedback from Consul users, we've evolved how prepared queries
|
||||
use ACLs. In this section we first cover the current implementation, and then we
|
||||
follow that with details about what's changed between specific versions of Consul.
|
||||
|
|
@ -381,17 +376,16 @@ These variations are covered here, with examples:
|
|||
way to define more specific policies. Clients can list or read queries for
|
||||
which they have "read" access based on their prefix, and similar they can
|
||||
update any queries for which they have "write" access. An example use for
|
||||
this type is a query with a well-known name (eg. prod-master-customer-db)
|
||||
this type is a query with a well-known name (eg. `prod-master-customer-db`)
|
||||
that is used and known by many clients to provide geo-failover behavior for
|
||||
a database.
|
||||
|
||||
#### Executing Pepared Queries
|
||||
|
||||
When prepared queries are executed via DNS lookups or HTTP requests, the
|
||||
management ACL isn't used in any way. Instead, ACLs are applied to the service
|
||||
being queried, similar to how other service lookups work, except that prepared
|
||||
queries have some special behavior related to where the ACL Token comes
|
||||
from:
|
||||
When prepared queries are executed via DNS lookups or HTTP requests, the ACL
|
||||
checks are run against the service being queried, similar to how ACLs work with
|
||||
other service lookups. There are several ways the ACL token is selected for this
|
||||
check:
|
||||
|
||||
* If an ACL Token was captured when the prepared query was defined, it will be
|
||||
used to perform the service lookup. This allows queries to be executed by
|
||||
|
|
@ -400,9 +394,14 @@ from:
|
|||
* If no ACL Token was captured, then the client's ACL Token will be used to
|
||||
perform the service lookup.
|
||||
|
||||
* If no ACL Token was captured, and the client has no ACL Token, then the
|
||||
* If no ACL Token was captured and the client has no ACL Token, then the
|
||||
anonymous token will be used to perform the service lookup.
|
||||
|
||||
In the common case, the ACL Token of the invoker is used
|
||||
to test the ability to look up a service. If a `Token` was specified when the
|
||||
prepared query was created, the behavior changes and now the captured
|
||||
ACL Token set by the definer of the query is used when lookup up a service.
|
||||
|
||||
Capturing ACL Tokens is analogous to
|
||||
[PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html)
|
||||
`SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL
|
||||
|
|
|
|||
Loading…
Reference in New Issue