website: Documenting ACL endpoints
This commit is contained in:
parent
4a61a8bd31
commit
8c5ae92fa7
|
@ -17,6 +17,7 @@ All endpoints fall into one of several categories:
|
||||||
* catalog - Manages nodes and services
|
* catalog - Manages nodes and services
|
||||||
* health - Manages health checks
|
* health - Manages health checks
|
||||||
* session - Session manipulation
|
* session - Session manipulation
|
||||||
|
* acl - ACL creations and management
|
||||||
* status - Consul system status
|
* status - Consul system status
|
||||||
* internal - Internal APIs. Purposely undocumented, subject to change.
|
* internal - Internal APIs. Purposely undocumented, subject to change.
|
||||||
|
|
||||||
|
@ -85,6 +86,14 @@ By default, the output of all HTTP API requests return minimized JSON with all
|
||||||
whitespace removed. By adding "?pretty" to the HTTP request URL,
|
whitespace removed. By adding "?pretty" to the HTTP request URL,
|
||||||
formatted JSON will be returned.
|
formatted JSON will be returned.
|
||||||
|
|
||||||
|
## ACLs
|
||||||
|
|
||||||
|
Several endpoints in Consul use or require ACL tokens to operate. An agent
|
||||||
|
can be configured to use a default token in requests using the `acl_token`
|
||||||
|
configuration option. However, the token can also be specified per-request
|
||||||
|
by using the "?token=" query parameter. This will take precedence over the
|
||||||
|
default token.
|
||||||
|
|
||||||
## KV
|
## KV
|
||||||
|
|
||||||
The KV endpoint is used to expose a simple key/value store. This can be used
|
The KV endpoint is used to expose a simple key/value store. This can be used
|
||||||
|
@ -99,7 +108,8 @@ are all supported. It is important to note that each datacenter has its
|
||||||
own K/V store, and that there is no replication between datacenters.
|
own K/V store, and that there is no replication between datacenters.
|
||||||
By default the datacenter of the agent is queried, however the dc can
|
By default the datacenter of the agent is queried, however the dc can
|
||||||
be provided using the "?dc=" query parameter. If a client wants to write
|
be provided using the "?dc=" query parameter. If a client wants to write
|
||||||
to all Datacenters, one request per datacenter must be made.
|
to all Datacenters, one request per datacenter must be made. The KV endpoint
|
||||||
|
supports the use of ACL tokens.
|
||||||
|
|
||||||
### GET Method
|
### GET Method
|
||||||
|
|
||||||
|
@ -1039,6 +1049,145 @@ It returns a JSON body like this:
|
||||||
|
|
||||||
This endpoint supports blocking queries and all consistency modes.
|
This endpoint supports blocking queries and all consistency modes.
|
||||||
|
|
||||||
|
## ACL
|
||||||
|
|
||||||
|
The ACL endpoints are used to create, update, destroy and query ACL tokens.
|
||||||
|
The following endpoints are supported:
|
||||||
|
|
||||||
|
* /v1/acl/create: Creates a new token with policy
|
||||||
|
* /v1/acl/update: Update the policy of a token
|
||||||
|
* /v1/acl/destroy/\<id\>: Destroys a given token
|
||||||
|
* /v1/acl/info/\<id\>: Queries the policy of a given token
|
||||||
|
* /v1/acl/clone/\<id\>: Creates a new token by cloning an existing token
|
||||||
|
* /v1/acl/list: Lists all the active tokens
|
||||||
|
|
||||||
|
### /v1/acl/create
|
||||||
|
|
||||||
|
The create endpoint is used to make a new token. A token has a name,
|
||||||
|
type, and a set of ACL rules. The name is opaque to Consul, and type
|
||||||
|
is either "client" or "management". A management token is effectively
|
||||||
|
like a root user, and has the ability to perform any action including
|
||||||
|
creating, modifying, and deleting ACLs. A client token can only perform
|
||||||
|
actions as permitted by the rules associated, and may never manage ACLs.
|
||||||
|
This means the request to this endpoint must be made with a management
|
||||||
|
token.
|
||||||
|
|
||||||
|
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
|
||||||
|
all requests are automatically routed to that datacenter regardless
|
||||||
|
of the agent that the request is made to.
|
||||||
|
|
||||||
|
The create endpoint expects a JSON request body to be PUT. The request
|
||||||
|
body must look like:
|
||||||
|
|
||||||
|
{
|
||||||
|
"Name": "my-app-token",
|
||||||
|
"Type": "client",
|
||||||
|
"Rules": "",
|
||||||
|
}
|
||||||
|
|
||||||
|
None of the fields are mandatory, and in fact no body needs to be PUT
|
||||||
|
if the defaults are to be used. The `Name` and `Rules` default to being
|
||||||
|
blank, and the `Type` defaults to "client". The format of `Rules` is
|
||||||
|
[documented here]().
|
||||||
|
|
||||||
|
The return code is 200 on success, along with a body like:
|
||||||
|
|
||||||
|
{"ID":"adf4238a-882b-9ddc-4a9d-5b6758e4159e"}
|
||||||
|
|
||||||
|
This is used to provide the ID of the newly created ACL token.
|
||||||
|
|
||||||
|
### /v1/acl/update
|
||||||
|
|
||||||
|
The update endpoint is used to modify the policy for a given
|
||||||
|
ACL token. It is very similar to the create endpoint, however
|
||||||
|
instead of generating a new token ID, the `ID` field must be
|
||||||
|
provided. Requests to this endpoint must be made with a management
|
||||||
|
token.
|
||||||
|
|
||||||
|
In any Consul cluster, only a single datacenter is authoritative for ACLs, so
|
||||||
|
all requests are automatically routed to that datacenter regardless
|
||||||
|
of the agent that the request is made to.
|
||||||
|
|
||||||
|
The update endpoint expects a JSON request body to be PUT. The request
|
||||||
|
body must look like:
|
||||||
|
|
||||||
|
{
|
||||||
|
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
|
||||||
|
"Name": "my-app-token-updated",
|
||||||
|
"Type": "client",
|
||||||
|
"Rules": "# New Rules",
|
||||||
|
}
|
||||||
|
|
||||||
|
Only the `ID` field is mandatory, the other fields provide defaults.
|
||||||
|
The `Name` and `Rules` default to being blank, and the `Type` defaults to "client".
|
||||||
|
The format of `Rules` is [documented here]().
|
||||||
|
|
||||||
|
The return code is 200 on success.
|
||||||
|
|
||||||
|
### /v1/acl/destroy/\<id\>
|
||||||
|
|
||||||
|
The destroy endpoint is hit with a PUT and destroys the given ACL token.
|
||||||
|
The request is automatically routed to the authoritative ACL datacenter.
|
||||||
|
The token being destroyed must be provided after the slash, and requests
|
||||||
|
to the endpoint must be made with a management token.
|
||||||
|
|
||||||
|
The return code is 200 on success.
|
||||||
|
|
||||||
|
### /v1/acl/info/\<id\>
|
||||||
|
|
||||||
|
This endpoint is hit with a GET and returns the token information
|
||||||
|
by ID. All requests are routed to the authoritative ACL datacenter
|
||||||
|
The token being queried must be provided after the slash.
|
||||||
|
|
||||||
|
It returns a JSON body like this:
|
||||||
|
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"CreateIndex":3,
|
||||||
|
"ModifyIndex":3,
|
||||||
|
"ID":"8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
||||||
|
"Name":"Client Token",
|
||||||
|
"Type":"client",
|
||||||
|
"Rules":"..."
|
||||||
|
}
|
||||||
|
]
|
||||||
|
|
||||||
|
If the session is not found, null is returned instead of a JSON list.
|
||||||
|
|
||||||
|
### /v1/acl/clone/\<id\>
|
||||||
|
|
||||||
|
The clone endpoint is hit with a PUT and returns a token ID that
|
||||||
|
is cloned from an existing token. This allows a token to serve
|
||||||
|
as a template for others, making it simple to generate new tokens
|
||||||
|
without complex rule management. The source token must be provided
|
||||||
|
after the slash. Requests to this endpoint require a management token.
|
||||||
|
|
||||||
|
The return code is 200 on success, along with a body like:
|
||||||
|
|
||||||
|
{"ID":"adf4238a-882b-9ddc-4a9d-5b6758e4159e"}
|
||||||
|
|
||||||
|
This is used to provide the ID of the newly created ACL token.
|
||||||
|
|
||||||
|
### /v1/acl/list
|
||||||
|
|
||||||
|
The list endpoint is hit with a GET and lists all the active
|
||||||
|
ACL tokens. This is a privileged endpoint, and requires a
|
||||||
|
management token.
|
||||||
|
|
||||||
|
It returns a JSON body like this:
|
||||||
|
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"CreateIndex":3,
|
||||||
|
"ModifyIndex":3,
|
||||||
|
"ID":"8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
|
||||||
|
"Name":"Client Token",
|
||||||
|
"Type":"client",
|
||||||
|
"Rules":"..."
|
||||||
|
},
|
||||||
|
...
|
||||||
|
]
|
||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
The Status endpoints are used to get information about the status
|
The Status endpoints are used to get information about the status
|
||||||
|
|
Loading…
Reference in New Issue