status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #674 from ryanbreen/acl 

Cleanups to docs/agent/http/acl
This commit is contained in:
Armon Dadgar 2015-02-05 09:43:40 -08:00
parent 0b0deff4ce a02bd2f586
commit 7caedac17a
1 changed files with 54 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
website/source/docs/agent/http/acl.html.markdown
View File

@ -3,16 +3,16 @@ layout: "docs"
page_title: "ACLs (HTTP)" page_title: "ACLs (HTTP)"
sidebar_current: "docs-agent-http-acl" sidebar_current: "docs-agent-http-acl"
description: > description: >
The ACL endpoints are used to create, update, destroy and query ACL tokens. The ACL endpoints are used to create, update, destroy, and query ACL tokens.
--- ---
# ACL HTTP Endpoint # ACL HTTP Endpoint
The ACL endpoints are used to create, update, destroy and query ACL tokens. The ACL endpoints are used to create, update, destroy, and query ACL tokens.
The following endpoints are supported: The following endpoints are supported:
* [`/v1/acl/create`](#acl_create): Creates a new token with policy * [`/v1/acl/create`](#acl_create): Creates a new token with a given policy
* [`/v1/acl/update`](#acl_update): Update the policy of a token * [`/v1/acl/update`](#acl_update): Updates the policy of a token
* [`/v1/acl/destroy/<id>`](#acl_destroy): Destroys a given token * [`/v1/acl/destroy/<id>`](#acl_destroy): Destroys a given token
* [`/v1/acl/info/<id>`](#acl_info): Queries the policy of a given token * [`/v1/acl/info/<id>`](#acl_info): Queries the policy of a given token
* [`/v1/acl/clone/<id>`](#acl_clone): Creates a new token by cloning an existing token * [`/v1/acl/clone/<id>`](#acl_clone): Creates a new token by cloning an existing token
@ -20,21 +20,27 @@ The following endpoints are supported:
### <a name="acl_create"></a> /v1/acl/create ### <a name="acl_create"></a> /v1/acl/create
The create endpoint is used to make a new token. A token has a name, 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 a type, and a set of ACL rules.
is either "client" or "management". A management token is effectively
like a root user, and has the ability to perform any action including The `Name` property is opaque to Consul. To aid human operators, it should
creating, modifying, and deleting ACLs. A client token can only perform be a meaningful indicator of the ACL's purpose.
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 Type is either `client` or `management`. A management token is comparable
token. to a root user and has the ability to perform any action including
creating, modifying, and deleting ACLs.
By constrast, a client token can only perform actions as permitted by the
rules associated. Client tokens can never manage ACLs. Given this limitation,
only a management token can be used to make requests to the `/v1/acl/create`
endpoint.
In any Consul cluster, only a single datacenter is authoritative for ACLs, so In any Consul cluster, only a single datacenter is authoritative for ACLs, so
all requests are automatically routed to that datacenter regardless all requests are automatically routed to that datacenter regardless
of the agent that the request is made to. of the agent to which the request is made.
The create endpoint expects a JSON request body to be PUT. The request The create endpoint supports a JSON request body with the PUT. The request
body must look like: body may take the form:
```javascript ```javascript
{ {
@ -44,12 +50,13 @@ body must look like:
} }
``` ```
None of the fields are mandatory, and in fact no body needs to be PUT None of the fields are mandatory. In fact, no body needs to be PUT if the
if the defaults are to be used. The `Name` and `Rules` default to being defaults are to be used. The `Name` and `Rules` fields default to being
blank, and the `Type` defaults to "client". The format of `Rules` is blank, and the `Type` defaults to "client".
[documented here](/docs/internals/acl.html).
The return code is 200 on success, along with a body like: The format of the `Rules` property is [documented here](/docs/internals/acl.html).
A successful response body will return the `ID` of the newly created ACL, like so:
```javascript ```javascript
{ {
@ -57,22 +64,20 @@ The return code is 200 on success, along with a body like:
} }
``` ```
This is used to provide the ID of the newly created ACL token.
### <a name="acl_update"></a> /v1/acl/update ### <a name="acl_update"></a> /v1/acl/update
The update endpoint is used to modify the policy for a given The update endpoint is used to modify the policy for a given ACL token. It
ACL token. It is very similar to the create endpoint, however is very similar to the create endpoint; however, instead of generating a new
instead of generating a new token ID, the `ID` field must be token ID, the `ID` field must be provided. As with [`/v1/acl/create`](#acl_create),
provided. Requests to this endpoint must be made with a management requests to this endpoint must be made with a management
token. token.
In any Consul cluster, only a single datacenter is authoritative for ACLs, so In any Consul cluster, only a single datacenter is authoritative for ACLs, so
all requests are automatically routed to that datacenter regardless all requests are automatically routed to that datacenter regardless
of the agent that the request is made to. of the agent to which the request is made.
The update endpoint expects a JSON request body to be PUT. The request The update endpoint requires a JSON request body to the PUT. The request
body must look like: body may look like:
```javascript ```javascript
{ {
@ -83,26 +88,22 @@ body must look like:
} }
``` ```
Only the `ID` field is mandatory, the other fields provide defaults. Only the `ID` field is mandatory. The other fields provide defaults: the
The `Name` and `Rules` default to being blank, and the `Type` defaults to "client". `Name` and `Rules` fields default to being blank, and `Type` defaults to "client".
The format of `Rules` is [documented here](/docs/internals/acl.html). The format of `Rules` is [documented here](/docs/internals/acl.html).
The return code is 200 on success.
### <a name="acl_destroy"></a> /v1/acl/destroy/\<id\> ### <a name="acl_destroy"></a> /v1/acl/destroy/\<id\>
The destroy endpoint is hit with a PUT and destroys the given ACL token. The destroy endpoint must be hit with a PUT. This endpoint destroys the ACL
The request is automatically routed to the authoritative ACL datacenter. token identified by the `id` portion of the path.
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. The request is automatically routed to the authoritative ACL datacenter.
Requests to this endpoint must be made with a management token.
### <a name="acl_info"></a> /v1/acl/info/\<id\> ### <a name="acl_info"></a> /v1/acl/info/\<id\>
This endpoint is hit with a GET and returns the token information The info endpoint must be hit with a GET. This endpoint returns the ACL
by ID. All requests are routed to the authoritative ACL datacenter token information identified by the `id` portion of the path.
The token being queried must be provided after the slash.
It returns a JSON body like this: It returns a JSON body like this:
@ -119,17 +120,20 @@ It returns a JSON body like this:
] ]
``` ```
If the session is not found, null is returned instead of a JSON list. If the ACL is not found, null is returned instead of a JSON list.
### <a name="acl_clone"></a> /v1/acl/clone/\<id\> ### <a name="acl_clone"></a> /v1/acl/clone/\<id\>
The clone endpoint is hit with a PUT and returns a token ID that The clone endpoint must be hit with a PUT. It clones the ACL identified
is cloned from an existing token. This allows a token to serve by the `id` portion of the path and returns a new token `ID`. This allows
as a template for others, making it simple to generate new tokens a token to serve as a template for others, making it simple to generate new
without complex rule management. The source token must be provided tokens without complex rule management.
after the slash. Requests to this endpoint require a management token.
The return code is 200 on success, along with a body like: The request is automatically routed to the authoritative ACL datacenter.
Requests to this endpoint must be made with a management token.
As with `create`, a successful response body will return the `ID` of the newly
created ACL, like so:
```javascript ```javascript
{ {
@ -137,12 +141,10 @@ The return code is 200 on success, along with a body like:
} }
``` ```
This is used to provide the ID of the newly created ACL token.
### <a name="acl_list"></a> /v1/acl/list ### <a name="acl_list"></a> /v1/acl/list
The list endpoint is hit with a GET and lists all the active The list endpoint must be hit with a GET. It lists all the active
ACL tokens. This is a privileged endpoint, and requires a ACL tokens. This is a privileged endpoint and requires a
management token. management token.
It returns a JSON body like this: It returns a JSON body like this: