github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/api-docs/acl/policies.mdx

394 lines
13 KiB
Markdown
Raw Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink