986355bcd9
The ACL command docs are now found within a sub-dir like the operator command docs. Updates to the ACL token commands to accommodate token expiry have also been added. The ACL API docs are now found within a sub-dir like the operator API docs. The ACL docs now include the ACL roles endpoint as well as updated ACL token endpoints for token expiration. The configuration section is also updated to accommodate the new ACL and server parameters for the new ACL features.
168 lines
4.7 KiB
Plaintext
168 lines
4.7 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: ACL Policies - HTTP API
|
|
description: The /acl/policy endpoints are used to configure and manage ACL policies.
|
|
---
|
|
|
|
# ACL Policies HTTP API
|
|
|
|
The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
|
|
For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control).
|
|
|
|
## List Policies
|
|
|
|
This endpoint lists all ACL policies. This lists the policies that have been replicated
|
|
to the region, and may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | --------------- | ------------------ |
|
|
| `GET` | `/acl/policies` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `YES` | `all` | `management` for all policies.<br />Output when given a non-management token will be limited to the policies on the token itself |
|
|
|
|
### Parameters
|
|
|
|
- `prefix` `(string: "")` - Specifies a string to filter ACL policies based on
|
|
a name prefix. This is specified as a query string parameter.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/acl/policies
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/acl/policies?prefix=prod
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Name": "foo",
|
|
"Description": "",
|
|
"CreateIndex": 12,
|
|
"ModifyIndex": 13
|
|
}
|
|
]
|
|
```
|
|
|
|
## Create or Update Policy
|
|
|
|
This endpoint creates or updates an ACL Policy. This request is always forwarded to the
|
|
authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------------- | -------------- |
|
|
| `POST` | `/acl/policy/:policy_name` | `(empty body)` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `Name` `(string: <required>)` - Specifies the name of the policy.
|
|
Creates the policy if the name does not exist, otherwise updates the existing policy.
|
|
|
|
- `Description` `(string: <optional>)` - Specifies a human readable description.
|
|
|
|
- `Rules` `(string: <required>)` - Specifies the Policy rules in HCL or JSON format.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "my-policy",
|
|
"Description": "This is a great policy",
|
|
"Rules": ""
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/policy/my-policy
|
|
```
|
|
|
|
## Read Policy
|
|
|
|
This endpoint reads an ACL policy with the given name. This queries the policy that have been
|
|
replicated to the region, and may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------------- | ------------------ |
|
|
| `GET` | `/acl/policy/:policy_name` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | ------------------------------------------- |
|
|
| `YES` | `all` | `management` or token with access to policy |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/acl/policy/foo
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Name": "foo",
|
|
"Rules": "",
|
|
"Description": "",
|
|
"CreateIndex": 12,
|
|
"ModifyIndex": 13
|
|
}
|
|
```
|
|
|
|
## Delete Policy
|
|
|
|
This endpoint deletes the named ACL policy. This request is always forwarded to the
|
|
authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | -------------------------- | -------------- |
|
|
| `DELETE` | `/acl/policy/:policy_name` | `(empty body)` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `policy_name` `(string: <required>)` - Specifies the policy name to delete.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
https://localhost:4646/v1/acl/policy/foo
|
|
```
|