github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cleans up the documents.

pull/1748/head
James Phillips 2016-02-24 18:05:58 -08:00
parent 7d392118d2
commit dca480e284
2 changed files with 31 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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 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 service. This is particularly useful in combination with Consul's
[DNS Interface](/docs/agent/dns.html) as it allows for much richer queries than [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: 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 When using the `POST` method, Consul will create a new prepared query and return
its ID if it is created successfully. 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. provided using the "?dc=" query parameter.
If ACLs are enabled, then the client will need to supply a token with `query` If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges sufficient to match the service name being queried and the `Name` write privileges for the `Name` of the query being created.
given to the query, if any. See also the note about the `Token` field below.
The create operation expects a JSON request body that defines the prepared query, The create operation expects a JSON request body that defines the prepared query,
like this example: 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. query must be manually removed when no longer needed.
<a name="token"></a> <a name="token"></a>
`Token` is a captured ACL Token to use when the query is executed. This allows `Token`, if specified, is a captured ACL Token that is reused as the ACL Token
queries to be executed by clients with lesser or even no ACL Token, so this every time the query is executed. This allows queries to be executed by clients
should be used with care. The token itself can only be seen by clients with a with lesser or even no ACL Token, so this should be used with care. The token
management token. If the `Token` field is left blank, the client's ACL Token itself can only be seen by clients with a management token. If the `Token`
will be used to determine if they have access to the service being queried. If field is left blank or omitted, the client's ACL Token will be used to determine
the client does not supply an ACL Token, the anonymous token will be used. 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 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 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. 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 provided using the "?dc=" query parameter. This endpoint supports blocking
queries and all consistency modes. 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. 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. provided using the "?dc=" query parameter.
If ACLs are enabled, then the client will need to supply a token with `query` If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges sufficient to match the service name being queried and the `Name` write privileges for the `Name` of the query being updated.
given to the query, if any.
The body is the same as is used to create a prepared query, as described above. 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. 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 provided using the "?dc=" query parameter. This endpoint supports blocking
queries and all consistency modes. queries and all consistency modes.
@ -240,12 +239,11 @@ management token is used.
The `DELETE` method is used to delete a prepared query. 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. provided using the "?dc=" query parameter.
If ACLs are enabled, then the client will need to supply a token with `query` If ACLs are enabled, the client will need to supply an ACL Token with `query`
write privileges sufficient to match the service name being queried and the `Name` write privileges for the `Name` of the query being deleted.
given to the query, if any.
No body is required as part of this request. 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 execute a prepared query. The \<query or name\> argument is the ID or name
of an existing prepared query. 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 provided using the "?dc=" query parameter. This endpoint does not support
blocking queries, but it does support all consistency modes. blocking queries, but it does support all consistency modes.

23
website/source/docs/internals/acl.html.markdown
View File

@ -348,11 +348,6 @@ service, then the DNS interface will return no records when queried for it.
<a name="prepared_query_acls"></a> <a name="prepared_query_acls"></a>
## Prepared Query ACLs ## 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 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 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. 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 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 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 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 that is used and known by many clients to provide geo-failover behavior for
a database. a database.
#### Executing Pepared Queries #### Executing Pepared Queries
When prepared queries are executed via DNS lookups or HTTP requests, the When prepared queries are executed via DNS lookups or HTTP requests, the ACL
management ACL isn't used in any way. Instead, ACLs are applied to the service checks are run against the service being queried, similar to how ACLs work with
being queried, similar to how other service lookups work, except that prepared other service lookups. There are several ways the ACL token is selected for this
queries have some special behavior related to where the ACL Token comes check:
from:
* If an ACL Token was captured when the prepared query was defined, it will be * 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 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 * If no ACL Token was captured, then the client's ACL Token will be used to
perform the service lookup. 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. 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 Capturing ACL Tokens is analogous to
[PostgreSQL’s](http://www.postgresql.org/docs/current/static/sql-createfunction.html) [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 `SECURITY DEFINER` attribute which can be set on functions, and using the client's ACL