website: Documenting ACL endpoints
This commit is contained in:
Armon Dadgar
parent
4a61a8bd31
commit
8c5ae92fa7
|
|
@ -17,6 +17,7 @@ All endpoints fall into one of several categories:
|
|||
* catalog - Manages nodes and services
|
||||
* health - Manages health checks
|
||||
* session - Session manipulation
|
||||
* acl - ACL creations and management
|
||||
* status - Consul system status
|
||||
* 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,
|
||||
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
|
||||
|
||||
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.
|
||||
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
|
||||
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
|
||||
|
||||
|
|
@ -1039,6 +1049,145 @@ It returns a JSON body like this:
|
|||
|
||||
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
|
||||
|
||||
The Status endpoints are used to get information about the status
|
||||
|
|
|
|||
Loading…
Reference in New Issue