mirror of https://github.com/hashicorp/consul
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
393 lines
13 KiB
393 lines
13 KiB
--- |
|
layout: api |
|
page_title: ACL Policies - HTTP API |
|
description: The /acl/policy endpoints manage Consul's ACL policies. |
|
--- |
|
|
|
# ACL Policy HTTP API |
|
|
|
The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy), |
|
[update](#update-a-policy), [list](#list-policies) and |
|
[delete](#delete-a-policy) ACL policies in Consul. |
|
|
|
For more information on how to setup ACLs, please check |
|
the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). |
|
|
|
## Create a Policy |
|
|
|
This endpoint creates a new ACL policy. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------- | ------------------ | |
|
| `PUT` | `/acl/policy` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl policy create`](/consul/commands/acl/policy/create). |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you create. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### JSON Request Body Schema |
|
|
|
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name |
|
can contain alphanumeric characters, dashes `-`, and underscores `_`. |
|
This name must be unique. |
|
|
|
- `Description` `(string: "")` - Free form human readable description of the policy. |
|
|
|
- `Rules` `(string: "")` - Specifies rules for the ACL policy. The format of the |
|
`Rules` property is detailed in the [ACL Rules documentation](/consul/docs/security/acl/acl-rules). |
|
|
|
- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within. |
|
When no datacenters are provided the policy is valid in all datacenters including |
|
those which do not yet exist but may in the future. |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you create. |
|
This field takes precedence over the `ns` query parameter, |
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace). |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"Name": "node-read", |
|
"Description": "Grants read access to all node information", |
|
"Rules": "node_prefix \"\" { policy = \"read\"}", |
|
"Datacenters": ["dc1"] |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/policy |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", |
|
"Name": "node-read", |
|
"Description": "Grants read access to all node information", |
|
"Rules": "node_prefix \"\" { policy = \"read\"}", |
|
"Datacenters": ["dc1"], |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"CreateIndex": 14, |
|
"ModifyIndex": 14 |
|
} |
|
``` |
|
|
|
## Read a Policy |
|
|
|
This endpoint reads an ACL policy with the given ID. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ----------------- | ------------------ | |
|
| `GET` | `/acl/policy/:id` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl policy read`](/consul/commands/acl/policy/read). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the policy you lookup. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", |
|
"Name": "node-read", |
|
"Description": "Grants read access to all node information", |
|
"Rules": "node_prefix \"\" { policy = \"read\"}", |
|
"Datacenters": ["dc1"], |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"CreateIndex": 14, |
|
"ModifyIndex": 14 |
|
} |
|
``` |
|
|
|
## Read a Policy by Name |
|
|
|
This endpoint reads an ACL policy with the given ID. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ------------------------ | ------------------ | |
|
| `GET` | `/acl/policy/name/:name` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl policy read -name=<string>`](/consul/commands/acl/policy/read#name). |
|
|
|
### Path Parameters |
|
|
|
- `name` `(string: <required>)` - Specifies the name of the ACL policy to read. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you lookup. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/name/node-read |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", |
|
"Name": "node-read", |
|
"Description": "Grants read access to all node information", |
|
"Rules": "node_prefix \"\" { policy = \"read\"}", |
|
"Datacenters": ["dc1"], |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"CreateIndex": 14, |
|
"ModifyIndex": 14 |
|
} |
|
``` |
|
|
|
## Update a Policy |
|
|
|
This endpoint updates an existing ACL policy. |
|
|
|
| Method | Path | Produces | |
|
| ------ | ----------------- | ------------------ | |
|
| `PUT` | `/acl/policy/:id` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl policy update`](/consul/commands/acl/policy/update). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the policy you update. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you update. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### JSON Request Body Schema |
|
|
|
- `ID` `(string: <optional>)` - If specified, this field must be an exact match |
|
with the `id` path parameter. |
|
|
|
- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name |
|
can only contain alphanumeric characters as well as `-` and `_` and must be |
|
unique. |
|
|
|
- `Description` `(string: "")` - Free form human readable description of this policy. |
|
|
|
- `Rules` `(string: "")` - Specifies rules for this ACL policy. The format of the |
|
`Rules` property is detailed in the [ACL Rules documentation](/consul/docs/security/acl/acl-rules). |
|
|
|
- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within. |
|
When no datacenters are provided the policy is valid in all datacenters including |
|
those which do not yet exist but may in the future. |
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you update. |
|
This field takes precedence over the `ns` query parameter, |
|
one of several [other methods to specify the namespace](#methods-to-specify-namespace). |
|
|
|
### Sample Payload |
|
|
|
```json |
|
{ |
|
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485", |
|
"Name": "register-app-service", |
|
"Description": "Grants write permissions necessary to register the 'app' service", |
|
"Rules": "service \"app\" { policy = \"write\"}" |
|
} |
|
``` |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request PUT \ |
|
--data @payload.json \ |
|
http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
{ |
|
"ID": "c01a1f82-44be-41b0-a686-685fb6e0f485", |
|
"Name": "register-app-service", |
|
"Description": "Grants write permissions necessary to register the 'app' service", |
|
"Rules": "service \"app\" { policy = \"write\"}", |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"CreateIndex": 14, |
|
"ModifyIndex": 28 |
|
} |
|
``` |
|
|
|
## Delete a Policy |
|
|
|
This endpoint deletes an ACL policy. |
|
|
|
| Method | Path | Produces | |
|
| -------- | ----------------- | ------------------ | |
|
| `DELETE` | `/acl/policy/:id` | `application/json` | |
|
|
|
Even though the return type is application/json, the value is either true or |
|
false indicating whether the delete succeeded. |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `NO` | `none` | `none` | `acl:write` | |
|
|
|
The corresponding CLI command is [`consul acl policy delete`](/consul/commands/acl/policy/delete). |
|
|
|
### Path Parameters |
|
|
|
- `id` `(string: <required>)` - Specifies the UUID of the policy you delete. |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the policy you delete. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
### Sample Request |
|
|
|
```shell-session |
|
$ curl --request DELETE \ |
|
http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 |
|
``` |
|
|
|
### Sample Response |
|
|
|
```json |
|
true |
|
``` |
|
|
|
## List Policies |
|
|
|
This endpoint lists all the ACL policies. |
|
|
|
| Method | Path | Produces | |
|
| ------ | --------------- | ------------------ | |
|
| `GET` | `/acl/policies` | `application/json` | |
|
|
|
The table below shows this endpoint's support for |
|
[blocking queries](/consul/api-docs/features/blocking), |
|
[consistency modes](/consul/api-docs/features/consistency), |
|
[agent caching](/consul/api-docs/features/caching), and |
|
[required ACLs](/consul/api-docs/api-structure#authentication). |
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | |
|
| ---------------- | ----------------- | ------------- | ------------ | |
|
| `YES` | `all` | `none` | `acl:read` | |
|
|
|
The corresponding CLI command is [`consul acl policy list`](/consul/commands/acl/policy/list). |
|
|
|
### Query Parameters |
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the auth methods in the specified namespace. |
|
The namespace may be specified as '\*' to return results for all namespaces. |
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace). |
|
|
|
## Sample Request |
|
|
|
```shell-session |
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/policies |
|
``` |
|
|
|
### Sample Response |
|
|
|
-> **Note** - The policies rules are not included in the listing and must be |
|
retrieved by the [policy reading endpoint](#read-a-policy) |
|
|
|
```json |
|
[ |
|
{ |
|
"CreateIndex": 4, |
|
"Datacenters": null, |
|
"Description": "Builtin Policy that grants unlimited access", |
|
"Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=", |
|
"ID": "00000000-0000-0000-0000-000000000001", |
|
"ModifyIndex": 4, |
|
"Name": "global-management" |
|
}, |
|
{ |
|
"CreateIndex": 14, |
|
"Datacenters": ["dc1"], |
|
"Description": "Grants read access to all node information", |
|
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", |
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", |
|
"ModifyIndex": 14, |
|
"Name": "node-read" |
|
} |
|
] |
|
``` |
|
|
|
## Methods to specify namespace <EnterpriseAlert inline /> |
|
|
|
ACL policy endpoints |
|
support several methods for specifying the namespace of the ACL policy resources |
|
with the following order of precedence: |
|
1. `Namespace` field of the JSON request body - |
|
only applies to [create](#create-a-policy) and [update](#update-a-policy) endpoints |
|
1. `ns` query parameter |
|
1. `X-Consul-Namespace` request header |
|
1. Namespace is inherited from the namespace of the request's ACL token (if any) |
|
1. The `default` namespace
|
|
|